Referencia

API de Ownbit MultiSig v1 (fase 1)

Tu propio sistema puede entregar listas de pagos a una multifirma de Ownbit. Una clave de API creada en la consola web envía borradores; los firmantes revisan cada línea y los inician en su teléfono. La API nunca mueve fondos.

Versión del 2026-11-18 (los borradores cambian por lineId; cinco estados de borrador). Este documento describe la fase 1 de la API. Todas las claves, hashes, direcciones y direcciones IP que aparecen en él son ejemplos inventados (las direcciones IP provienen de los rangos reservados para documentación); la dirección del contrato de USDT-TRC20 es la real y pública.

1. Qué hace la API

Tu sistema (en adelante, "tu bot") le entrega a Ownbit una lista de pagos para una multifirma de Ownbit, un borrador, y más tarde consulta qué fue de él: si un firmante lo inició, lo rechazó, si se retiró o si caducó.

La API nunca mueve fondos. Un borrador se convierte en pagos solo cuando un firmante de la multifirma lo abre en la consola web de Ownbit, lo inicia en su propio teléfono y suficientes miembros de la multifirma firman cada transacción (m de n). Los firmantes ven cada línea antes de iniciarla, se siguen aplicando todas las comprobaciones que Ownbit hace sobre un pago, y un firmante puede rechazar un borrador. Una clave no puede firmar, iniciar un pago, aprobar, rechazar ni cambiar la política, la lista blanca o los miembros de la multifirma.

Lo que puede hacer una clave:

LlamadaPermisoQué hace
GET /whoamidrafts:readDescribe la clave y su multifirma, con los recuentos de llamadas del día
POST /draftsdrafts:submitEnvía un borrador (de 1 a 500 líneas), o modifica uno que nadie ha iniciado: agrega, reemplaza y quita líneas por tu lineId
GET /draftsdrafts:readLista los borradores de esta clave, del cambio más antiguo al más reciente, con un cursor
GET /drafts/{draftId}drafts:readLee un borrador con sus líneas
DELETE /drafts/{draftId}drafts:submitRetira un borrador que nadie ha iniciado

2. Alcance de la fase 1

  • Solo multifirmas en TRON. Las líneas pagan en TRX o USDT (USDT-TRC20, contrato TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); ambos tienen 6 decimales.
  • Solo IPv4. A la API solo se accede por IPv4 (api.bittool.com no tiene dirección IPv6 en la fase 1), y la lista de IP permitidas de una clave contiene rangos IPv4.
  • Sin webhooks. Tu bot consulta periódicamente (la sección 10 indica con qué frecuencia).
  • Como máximo 500 líneas por borrador. Un firmante puede iniciar un borrador grande como dos solicitudes en su teléfono; eso no cambia nada para ti.

3. URL base y transporte

https://api.bittool.com/ownbit/api/v1
  • Solo IPv4 en la fase 1: el nombre no tiene dirección IPv6, así que un servidor con IPv4 e IPv6 llama por IPv4 y se compara con su lista de IP permitidas IPv4.
  • Solo HTTPS. Una solicitud que no llega por HTTPS se rechaza con 403 https_required y nunca se redirige. Una clave que se haya enviado por HTTP sin cifrar debe considerarse filtrada: revócala y crea otra. Las respuestas HTTPS llevan Strict-Transport-Security: max-age=31536000.
  • JSON en UTF-8. Las solicitudes POST envían Content-Type: application/json (se acepta el sufijo ; charset=utf-8). El cuerpo de una solicitud ocupa como máximo 256 KiB.
  • Las horas son cadenas ISO 8601 en UTC con milisegundos, por ejemplo 2026-11-17T06:00:00.000Z.
  • Toda respuesta lleva Cache-Control: no-store, Pragma: no-cache y X-Request-Id (req_ seguido de 16 caracteres de [0-9a-z]). Los cuerpos de error lo repiten como requestId. Indícalo cuando contactes a soporte.
  • Sin CORS. Ninguna página de navegador puede llamar a la API: llámala desde tu servidor.
  • Solicitudes estrictas, respuestas abiertas. Una solicitud con un campo que la API no conoce se rechaza (400 invalid_request). Las respuestas pueden incorporar campos nuevos con el tiempo: ignora los campos que no conozcas.

4. Claves

  • De dónde salen. Un miembro de la multifirma crea una clave en la consola web de Ownbit, en la pestaña API de la multifirma (puede hacerlo cualquier miembro con el rol de firmante), y la autoriza en su teléfono con la app de Ownbit. La clave se muestra una sola vez, en esa pestaña del navegador, justo después de que el teléfono la autoriza. Ownbit guarda solo un hash de ella y no puede volver a mostrarla: si se pierde, revócala y crea otra.
  • Formato. obk_ seguido de 43 caracteres de [0-9A-Za-z] (47 caracteres en total, unos 256 bits de aleatoriedad). En todos los lugares donde Ownbit muestra una clave, muestra solo sus últimos 4 caracteres, como obk_…defg.
  • Opciones elegidas al crearla. Un nombre (como máximo 30 caracteres, distinto del de las demás claves de la multifirma); una validez de 30, 90 (predeterminada), 180 o 365 días, 2 años o 5 años, contada desde la autorización del teléfono; una lista de IP permitidas IPv4 de hasta 20 rangos, cada uno de /8 a /32 (una lista vacía significa cualquier dirección); y el máximo de líneas de pago que la clave puede enviar en cualquier periodo de 24 horas (de 1 a 10,000; 1,000 de forma predeterminada).
  • Permisos. Toda clave de la fase 1 tiene drafts:submit y drafts:read.
  • Una multifirma. Una clave cubre una dirección de multifirma: su TRX y, cuando existe, su USDT en esa dirección. Ownbit puede listar una dirección como varias multifirmas, una por token; comparten las mismas claves. Una clave nunca ve los datos de otra multifirma.
  • Como máximo 5 claves por multifirma (incluidas las pendientes).
  • Revocación. Cualquier miembro puede revocar una clave en cualquier momento, en la consola web o en la app de Ownbit. Una clave revocada o caducada falla al instante. Revocar una clave también rechaza sus borradores que nadie ha iniciado (motivo key_revoked); los borradores ya iniciados continúan.
  • Notificaciones. El teléfono de cada miembro recibe un aviso cuando se autoriza o se revoca una clave. Si tu equipo ve un aviso así que no esperaba, revoca la clave.

5. Autenticación

Envía la clave en cada llamada, y solo en esta cabecera:

Authorization: Bearer obk_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefg

Nunca pongas una clave en una URL, una cadena de consulta o un cuerpo.

curl -sS https://api.bittool.com/ownbit/api/v1/whoami \
  -H "Authorization: Bearer $OWNBIT_API_KEY"
  • Todo problema con la clave recibe la misma respuesta: 401 {"error":{"code":"unauthorized","message":"Invalid or unusable API key"},"requestId":"req_…"}. Eso abarca una cabecera ausente o mal formada, una clave desconocida, una clave aún no autorizada, una clave revocada o caducada, una dirección de origen fuera de la lista de IP permitidas de la clave, un creador que ya no es miembro o ya no tiene el rol de firmante, y una multifirma que ya no está activa. Los miembros de la multifirma ven en la consola web el último rechazo de cada clave y su motivo, así que pregúntales cuando no sepas por qué.
  • Una clave válida sin el permiso que necesita una llamada recibe 403 forbidden.
  • Un 401 no se resuelve reintentando. Detente y haz que una persona lo revise (sección 10.4: los fallos repetidos bloquean tu dirección).

6. Llamadas

6.1 GET /whoami

{"keyId":"kid_0123456789abcdef","name":"Payout bot","hint":"defg","perms":["drafts:submit","drafts:read"],
 "createdAt":"2026-11-17T06:00:00.000Z","expiresAt":"2027-02-15T06:05:00.000Z","ipAllow":["203.0.113.0/24"],
 "dailyLines":1000,"linesUsed24h":200,
 "callsToday":2880,"dailyCalls":10000,"multisigCallsToday":3105,"multisigDailyCalls":20000,
 "callsResetAt":"2026-11-18T00:00:00.000Z",
 "multisig":{"msId":4001,"chain":"TRX","address":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","name":"Payroll",
   "isEnterprise":true,"requiredNum":2,"ownerNum":4,"symbols":["TRX","USDT"],"defaultSymbol":"TRX"}}
  • dailyLines, linesUsed24h: el límite de líneas de la clave y las líneas que envió en las últimas 24 horas.
  • callsToday, dailyCalls: las llamadas de esta clave contadas desde las 00:00 UTC (incluida esta) y su tope diario de llamadas. multisigCallsToday, multisigDailyCalls: lo mismo para todas las claves de la multifirma juntas. callsResetAt: cuándo se reinician los recuentos diarios (sección 10).
  • multisig.symbols: los símbolos en los que puedes pagar. multisig.defaultSymbol: el símbolo en el que paga una línea sin symbol. En una multifirma de TRON es TRX, no USDT: envía symbol en cada línea (sección 6.2).
  • requiredNum de ownerNum: las firmas que necesita cada pago.

6.2 POST /drafts

Una llamada crea un borrador, y las llamadas posteriores con el mismo clientRequestId lo modifican: agregan líneas, reemplazan líneas y quitan líneas, cada una identificada por tu propio lineId. Un borrador solo se puede modificar mientras nadie lo haya iniciado (estado submitted).

Solicitud (exactamente estas claves; cualquier otra cosa es 400 invalid_request):

{"clientRequestId":"payout-2026-11-17-001",
 "lines":[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},
          {"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT"}]}

Una llamada posterior que agrega una línea, modifica po-1 y quita po-2:

{"clientRequestId":"payout-2026-11-17-001",
 "lines":[{"lineId":"po-3","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"0.03","symbol":"USDT"},
          {"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"130","symbol":"USDT","memo":"INV-1001"}],
 "remove":["po-2"]}
CampoRegla
clientRequestIdDe 1 a 64 caracteres de [A-Za-z0-9._:-], tu propio identificador para esta lista de pagos. Identifica un único borrador de la multifirma, para siempre (sección 6.2.2)
linesDe 0 a 500 objetos, cada uno solo con las claves siguientes. La primera llamada debe enviar al menos uno
removeOpcional. Los lineId de las líneas que se deben quitar del borrador. Un lineId que el borrador no tiene se ignora, así que reintentar es seguro. Un lineId no puede estar a la vez en lines y en remove
lineIdObligatorio. De 1 a 64 caracteres de [A-Za-z0-9._:/-], tu propio identificador para la línea, único dentro del borrador (otro clientRequestId empieza de cero). Un lineId que el borrador ya tiene reemplaza esa línea en su lugar; uno nuevo se agrega al final. Se te devuelve; nunca se registra en la cadena y nunca se muestra a los firmantes
toUna dirección de TRON (34 caracteres, base58check). No la propia dirección de la multifirma, no la dirección cero de TRON T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb, no el contrato de USDT (los tokens enviados ahí se pierden)
amountUna cadena que cumpla ^(0|[1-9][0-9]*)(\.[0-9]+)?$, mayor que cero, con como máximo 6 decimales contados tal como se envían ("1.0000000" se rechaza con amount_decimals; "80.500000" se acepta y se guarda como "80.5"), como máximo 9223372036854775807 en la unidad mínima. Envía una cadena, nunca un número JSON. Ownbit la guarda en forma canónica: se eliminan los ceros finales de la parte fraccionaria y luego un punto suelto ("80.50" pasa a ser "80.5", "2.0" pasa a ser "2")
symbolTRX o USDT. Envíalo en cada línea. Si lo omites, la línea paga en el defaultSymbol de la multifirma, que en una multifirma de TRON es TRX: un pago en USDT sin symbol se convertiría en un pago en TRX por la misma cifra. La multifirma debe tener ese símbolo (lo indica whoami en symbols)
memoOpcional. Como máximo 80 caracteres; ninguno de , ' " \; sin caracteres de control, saltos de línea ni caracteres invisibles; sin espacios al principio ni al final; no puede ser un memo reservado (que empiece con admin:, que contenga -no-broadcast o que termine en ***br***, sin distinguir mayúsculas y minúsculas). Omitirlo y "" equivalen a lo mismo

Ownbit primero quita las líneas de remove, luego reemplaza o agrega cada línea de lines y después revisa el borrador en conjunto: como máximo 500 líneas, al menos una, y no puede haber dos líneas con el mismo to, el mismo amount canónico y el mismo symbol (la cadena rechazaría la segunda como duplicada mientras la primera espera firmas). Cada línea que envías se revisa igual que en la primera llamada; si algo se rechaza, no cambia nada.

Respuestas:

EstadoCuerpoCuándo
201{"draft":<draft>}Un borrador nuevo, con estado submitted, revisión 1 y cada línea en pending
200{"draft":<draft>}El borrador cambió (su revision aumentó en uno), o la llamada no cambió nada (un reintento): el borrador tal como está ahora
409 not_editabledetails.draftId, details.statusEl borrador ya no está en submitted (un firmante lo inició, o fue retirado, rechazado o caducó): no cambió nada
409 idempotency_conflictOtra clave de la misma multifirma ya usó el clientRequestId
410 goneEl borrador de este clientRequestId se eliminó (conservación, sección 7.3)
422 invalid_linesdetails.errorsUna o más líneas no son válidas, o el borrador quedaría vacío; no cambió nada
429 daily_limitdetails.scopeSe superaría el límite de líneas de 24 horas de la clave o de la multifirma (sección 10). Con details.neverFits: true y sin Retry-After, esta llamada por sí sola tiene más líneas que el límite, así que esperar nunca sirve: envía menos líneas por llamada

details.errors lista los primeros 50 problemas como {"line":<index in lines>,"lineId":"po-1","field":"amount","reason":"amount_decimals"}. Motivos: line_id_invalid, line_id_duplicate, address_invalid, address_self, address_zero, address_contract, amount_invalid, amount_zero, amount_decimals, amount_too_large, symbol_unknown, symbol_unavailable, memo_invalid, memo_reserved, duplicate_line, draft_empty (line y lineId son null: quitar líneas dejaría el borrador sin ninguna; en su lugar, retira el borrador, sección 6.5).

6.2.1 El borrador

La forma completa (la forma de la lista no tiene lines):

{"draftId":"drf_0123456789abcdefghijklmn","clientRequestId":"payout-2026-11-17-001","status":"started","revision":1,
 "createdAt":"2026-11-17T06:10:00.000Z","updatedAt":"2026-11-17T06:31:12.000Z","startedAt":"2026-11-17T06:31:12.000Z","lineCount":2,
 "contentHash":"cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4",
 "totals":[{"symbol":"USDT","amount":"205.5"}],"counts":{"started":2},"rejection":null,
 "lines":[{"index":0,"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001",
           "repeated":false,"state":"started"},
          {"index":1,"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":"",
           "repeated":false,"state":"started"}]}
  • draftId: drf_ seguido de 24 caracteres de [0-9a-z].
  • revision: 1 para un borrador nuevo, y uno más después de cada llamada que lo modificó.
  • startedAt: cuándo un firmante inició el borrador por primera vez en su teléfono; si no, null. No cambia cuando un firmante lo vuelve a iniciar.
  • lines[].lineId: tu identificador de la línea. lines[].index: su posición actual, desde 0 (cambia cuando se quita una línea anterior: empareja las líneas por lineId). memo es "" cuando no existe.
  • lines[].state: siempre sigue el estado del borrador (sección 7.2). En la fase 1 una línea no lleva identificador de transacción, hash, recuento de firmas ni error: comprueba los pagos como indica la sección 8.
  • totals: la suma por símbolo; counts: el número de líneas en cada estado (solo los estados que tienen líneas).
  • repeated: true cuando otro borrador de esta multifirma de los últimos 7 días tiene una línea con la misma dirección, el mismo monto y el mismo símbolo. Los firmantes ven la marca y deben confirmarla antes de iniciar el borrador; revisa tu propio sistema cuando la veas.
  • rejection: {"reason","note","at"} cuando el borrador fue rechazado; si no, null. Motivos: whitelist, address, amount, duplicate, other (los elige un firmante en la consola web, que puede añadir una note de una línea), phone (un firmante lo rechazó en su teléfono; sin note) y key_revoked. La API nunca dice qué miembro lo rechazó.

6.2.2 Reintentos y cambios

  • clientRequestId identifica un único borrador de la multifirma para siempre: sigue usado mientras se conserve su borrador y durante 365 días después de que el borrador se elimine (410). Solo la clave que creó el borrador puede modificarlo; otra clave de la misma multifirma recibe 409 idempotency_conflict (tras una rotación de claves, usa identificadores nuevos). Haz que tus identificadores sean únicos para siempre, por ejemplo una fecha más un número de secuencia.
  • Toda llamada se puede reintentar con seguridad. Después de un tiempo de espera agotado o de un error de red, vuelve a enviar la misma solicitud: las líneas que enviaste se reemplazan a sí mismas con el mismo contenido y las líneas quitadas ya no están, así que la respuesta es el borrador tal como está, nunca un segundo borrador ni una segunda copia de una línea.
  • Solo se puede modificar un borrador mientras está en submitted. Una vez que un firmante lo inicia, una llamada responde 409 not_editable: pide a los firmantes que rechacen las líneas que no se deben pagar y envía las nuevas con un clientRequestId nuevo.
  • Los firmantes ven el borrador tal como está cuando lo abren. Si cambia mientras un firmante lo tiene abierto, su consola se niega a iniciarlo y le pide que lo vuelva a abrir.
  • Dos llamadas simultáneas con el mismo identificador se aplican una después de la otra.

6.2.3 El hash del contenido

contentHash es el SHA-256 en hexadecimal y minúsculas de los bytes UTF-8 del arreglo JSON compacto de las líneas del borrador en su orden, cada una escrita como {"lineId","to","amount","symbol","memo"} en ese orden, con el monto canónico, el símbolo siempre escrito y "" para un memo ausente. Cambia con cada modificación del borrador. Para la primera solicitud anterior:

[{"lineId":"po-1","to":"TM8pAQuHiAbbSGir19eBLGapFkpjYbFgS5","amount":"125.5","symbol":"USDT","memo":"INV-1001"},{"lineId":"po-2","to":"TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV","amount":"80","symbol":"USDT","memo":""}]

→ cc43baacd7df98efac68139dd9be5dba47d4fa0343c034e3fd54098409cf59a4. Arma la cadena tú mismo (no hace falta el orden de claves ni el escape de ninguna biblioteca JSON: ninguno de estos campos puede contener un carácter que necesite escape). La huella que ven los firmantes son los primeros 16 caracteres hexadecimales de contentHash (aquí, cc43baacd7df98ef). La sección 8 explica qué hacer con ellos.

6.3 GET /drafts?since=<cursor>&limit=<n>

Los borradores de esta clave, ordenados por updatedAt y luego por draftId, después del cursor (sin since: desde el más antiguo que se conserva). limit va de 1 a 100, 50 de forma predeterminada.

{"drafts":[<draft without lines>],"nextCursor":"<opaque>","hasMore":false}

El updatedAt de un borrador avanza cada vez que cambian su estado o sus líneas, así que consultar con el último nextCursor permite ver cada cambio. Una página vacía devuelve el cursor que enviaste; sigue usándolo. Un cursor que no se puede leer da 400 invalid_request.

6.4 GET /drafts/{draftId}

200 {"draft":<draft>}. Un borrador de otra clave (aunque sea de la misma multifirma), o uno que ya no se conserva: 404 not_found.

6.5 DELETE /drafts/{draftId}

Retira un borrador que nadie ha iniciado. Solo mientras su estado sea submitted: cada línea pasa a withdrawn, 200 {"draft":<draft>}. Si ya está en withdrawn: 200 de nuevo. En cualquier otro caso, 409 not_withdrawable con details.status. Una vez que un firmante ha iniciado un borrador, pide a los firmantes que rechacen lo que queda.

7. Estados

7.1 status del borrador

EstadoSignificado
submittedNadie lo ha iniciado todavía. Solo en este estado tu bot puede modificarlo (sección 6.2) o retirarlo (sección 6.5)
startedUn firmante lo inició en su teléfono (startedAt indica cuándo ocurrió eso por primera vez). Un firmante puede abrirlo e iniciarlo de nuevo, por ejemplo si su teléfono se detuvo a medio camino; sigue en started
rejectedUn firmante lo rechazó, en la consola web o en su teléfono (antes o después de que se iniciara), o su clave se revocó antes de que alguien lo iniciara. rejection indica el motivo
withdrawnTu bot lo retiró
expiredNadie lo inició en 7 días

Ownbit informa solo lo que sabe con certeza: que un firmante inició el borrador en su teléfono. No sabe qué pagos se hicieron después, así que un borrador en started puede estar pagado por completo, en parte o nada. Los pagos son transacciones de la multifirma: compruébalos como indica la sección 8, y no vuelvas a enviar las líneas de un borrador iniciado a menos que los firmantes te digan que no se pagaron.

7.2 state de la línea

El state de una línea siempre es el de su borrador: en la fase 1 Ownbit no sigue la transacción de cada línea.

EstadoSignificado
pendingEl borrador está en submitted
startedEl borrador está en started
rejected, withdrawn, expiredEl estado del borrador

7.3 Duración

Un borrador que nadie inicia caduca a los 7 días. Un borrador iniciado sigue en started hasta que un firmante lo rechaza. Los borradores rechazados, retirados y caducados se conservan 30 días después de terminar, y un borrador iniciado, 30 días después de su último cambio; luego se eliminan (GET responde entonces 404; el mismo clientRequestId responde 410 durante 365 días más).

8. Comprobar lo que se paga

Ownbit lleva tu lista desde tu bot hasta las pantallas de los firmantes. Para asegurarte de que nada cambió en el camino:

  1. Muestra el clientRequestId y la huella (los primeros 16 caracteres hexadecimales de contentHash) en tu propio canal de aprobación, junto a la lista de pagos aprobada. Un borrador que modificas tiene una huella nueva: muestra la más reciente. Los firmantes ven ambos en la consola web, recalculados por su navegador a partir de las líneas que están por iniciar, y se les pide que los comparen con tu registro. Esa comparación solo es posible si tu registro de aprobación los muestra.
  2. Recalcula contentHash (sección 6.2.3) a partir de las líneas de cada borrador que leas, y compáralo con el valor que calculaste para la última revisión del borrador.
  3. Comprueba tú mismo en la cadena los pagos de la multifirma. En la fase 1 Ownbit no informa la transacción de cada línea. Una vez que un borrador está en started, compara sus líneas con las transacciones salientes de la dirección de la multifirma (en whoami, el campo multisig.address): el destinatario, el monto y el token de cada pago deben coincidir con los de una de tus líneas, y cada línea debería pagarse como máximo una vez.
  4. Vigila repeated: una línea que repite una de otro borrador reciente se marca para los firmantes; también debería marcarse en tu sistema.
  5. En una multifirma empresarial, pide a sus miembros que activen la lista blanca y un límite diario: así ni siquiera un borrador erróneo puede pagar a una dirección desconocida ni más del límite. Las demás multifirmas no tienen lista blanca, así que la revisión de los firmantes es la única.

9. Errores

Todo error tiene este cuerpo:

{"error":{"code":"<code>","message":"<English sentence>","details":{}},"requestId":"req_0123456789abcdef"}

message es una frase fija en inglés pensada para personas; programa según code y details. Los mensajes nunca repiten lo que enviaste.

HTTPcodeCuándo
400invalid_requestNo es JSON, un tipo incorrecto, un campo desconocido, un clientRequestId no válido, ninguna línea o más de 500, un cursor o un límite no válidos, un cuerpo de solicitud que no llegó en 10 segundos
401unauthorizedCualquier problema con la clave (sección 5)
403forbiddenUna clave válida sin el permiso de la llamada
403https_requiredLa solicitud no llegó por HTTPS (revoca la clave que llevaba)
404not_foundUna ruta desconocida; un borrador que no es de esta clave o que ya no se conserva
405method_not_allowedUn método que la ruta no acepta (incluido OPTIONS)
409idempotency_conflictSección 6.2
409not_editableSección 6.2 (details.status)
409not_withdrawableSección 6.5 (details.status)
410goneUn clientRequestId cuyo borrador se eliminó
413too_largeUn cuerpo de más de 256 KiB
415unsupported_media_typeUn POST que no es JSON
422invalid_linesSección 6.2 (details.errors)
429rate_limited, daily_limitUn límite (sección 10), con Retry-After, details.scope, details.limit, details.retryAfter
500internalUn error del lado de Ownbit; reintenta más tarde
503unavailableLa API está desactivada o no puede responder en este momento; con details.scope api_busy y Retry-After cuando está saturada

Un 429 con alcance edge, o un 413, que proviene de la capa de protección situada delante de la API tiene la misma forma con "requestId":null.

10. Límites de solicitudes y topes diarios

10.1 Los límites

LímiteValordetails.scopecode
Solicitudes desde una dirección, ráfaga20 por segundo (ráfagas de hasta 40), 20 conexiones abiertasedgerate_limited
Llamadas por clave10 por segundokey_secondrate_limited
Llamadas por clave300 por minutokey_minuterate_limited
POST /drafts por clave60 por horakey_submit_hourrate_limited
Llamadas en curso a la vez, por clave2key_concurrentrate_limited
Llamadas en curso a la vez, por multifirma (todas sus claves)4multisig_concurrentrate_limited
Llamadas por dirección (claves válidas)600 por minuto; nunca rechaza una clave cuya lista de IP permitidas no está vacía y contiene la direcciónip_minuterate_limited
Llamadas por clave10,000 al díakey_dayrate_limited
Llamadas por multifirma (todas sus claves juntas)20,000 al díamultisig_dayrate_limited
Llamadas por dirección (claves válidas)50,000 al día; nunca rechaza una clave cuya lista de IP permitidas no está vacía y contiene la direcciónip_dayrate_limited
Llamadas por dirección (claves válidas), tope absoluto200,000 al día, para todas las clavesip_day (details.limit 200000)rate_limited
Llamadas fallidas por dirección20 por minuto; si se supera, la dirección queda retenida 10 minutosip_failuresrate_limited
Llamadas fallidas por dirección200 al día; si se supera, la dirección queda bloqueada 24 horasip_blockedrate_limited
Llamadas fallidas por red (una /24)1,000 al día; si se supera, la red queda bloqueada 24 horasnet_blockedrate_limited
Líneas de pago por claveel límite propio de la clave (de 1 a 10,000; 1,000 de forma predeterminada) en cualquier periodo de 24 horaskey_lines_24hdaily_limit
Líneas de pago por multifirma10,000 en cualquier periodo de 24 horasmultisig_lines_24hdaily_limit
Toda la API saturada(protege el servicio)api_busy (HTTP 503)unavailable
  • Un día es el día calendario UTC: los topes de llamadas y los topes de fallos se reinician a las 00:00 UTC (las 08:00 en Pekín). Los dos límites de líneas son móviles: cualquier periodo de 24 horas.
  • Qué cuenta. Toda llamada hecha con una clave válida cuenta para los límites de la clave, de la multifirma y de la dirección: también las lecturas, las llamadas rechazadas después de aceptar la clave (un 403, 404, 409, 422 o el 429 de un límite de líneas) y un POST /drafts repetido. Una llamada rechazada por un límite de solicitudes o un tope no cuenta para ninguno de ellos, así que esperar lo que indica Retry-After siempre funciona. Una llamada cuya clave se rechaza (401) solo cuenta para las llamadas fallidas de su dirección y de su red.
  • Una dirección o red retenida o bloqueada (retenida 10 minutos o bloqueada 24 horas) sigue atendiendo a toda clave que sea válida y cuya lista de IP permitidas admita la dirección (una lista vacía las admite todas). Ahí solo se rechazan las llamadas con claves no válidas y con claves cuya lista de IP permitidas no admite la dirección. Por eso, una clave válida nunca queda bloqueada por los fallos de otras personas desde la misma dirección.
  • Los límites por dirección se comparten con todos los que llaman desde ella. Una clave cuya lista de IP permitidas no está vacía y contiene la dirección no es rechazada por el límite de 600 por minuto ni por el de 50,000 al día, pero el límite de ráfaga (20 por segundo) y el tope absoluto (200,000 al día) cuentan a todos los que usan la dirección, así que en un NAT compartido, un runner de CI o una salida de nube otros todavía pueden ralentizar tus llamadas; y un 429 con alcance ip_minute o ip_day te indica que otros en tu dirección están muy activos. Usa una dirección de salida dedicada.

10.2 Las respuestas

Un límite responde 429 (o 503 para api_busy) con:

{"error":{"code":"rate_limited","message":"Daily call limit of this key reached",
  "details":{"scope":"key_day","limit":10000,"retryAfter":31260}},"requestId":"req_0123456789abcdef"}

y la cabecera Retry-After: 31260: los segundos enteros que hay que esperar (al menos 1). Llega hasta el final de la ventana, de la retención o del bloqueo; hasta las 00:00 UTC para los topes diarios de llamadas; para los límites de líneas, hasta que suficientes de tus líneas más antiguas salgan del periodo de 24 horas (al menos 60 segundos); 1 para edge y los dos alcances _concurrent; para api_busy, de 1 a unos 90 segundos, con una parte aleatoria para que los clientes rechazados no vuelvan todos a la vez. Cuando varios límites rechazan a la vez, la respuesta nombra el de mayor espera. details.limit es el valor de ese límite (no se da para api_busy). El único 429 sin Retry-After es un borrador que nunca puede caber en su límite de líneas: details.neverFits es true y details.retryAfter es null (sección 6.2).

Los mensajes: Too many requests from this address (edge, ip_minute), Too many failed requests from this address (ip_failures), This address is blocked after too many failed requests (ip_blocked), This network is blocked after too many failed requests (net_blocked), Too many requests for this key (key_second, key_minute), Too many concurrent requests for this key (key_concurrent), Too many concurrent requests for this multisig (multisig_concurrent), Too many drafts submitted with this key in the last hour (key_submit_hour), Daily call limit of this key reached (key_day), Daily call limit of this multisig reached (multisig_day), Daily call limit of this address reached (ip_day), Line limit of this key for 24 hours reached (key_lines_24h), Line limit of this multisig for 24 hours reached (multisig_lines_24h), The API is busy, retry later (api_busy).

10.3 Las cabeceras

Toda respuesta a una llamada cuya clave fue aceptada (los éxitos, los errores posteriores y sus 429) lleva:

CabeceraValor
X-RateLimit-LimitEl tope diario de llamadas de la clave (10000)
X-RateLimit-RemainingLo que queda hoy después de esta llamada: el menor entre lo que les queda a la clave y a su multifirma
X-RateLimit-ResetLas próximas 00:00 UTC, en segundos Unix (el 2026-11-17: 1794960000)

Un 401, un 429 de edge, ip_failures, ip_blocked o net_blocked, y un 503 no llevan ninguna de ellas. GET /whoami da los mismos recuentos en su cuerpo (callsToday, multisigCallsToday, callsResetAt).

10.4 Cómo consulta y se retrae un bot bien hecho

  • Consulta GET /drafts?since=<last nextCursor> cada 30 segundos, con un solo proceso de consulta por clave. Eso son 2,880 llamadas al día. Si varias copias de tu bot comparten una clave, deja que una de ellas consulte y comparta lo que lee. Conserva el último nextCursor entre reinicios; una página vacía lo devuelve sin cambios. Cuando hasMore es true, lee la página siguiente de inmediato.
  • Nunca consultes más rápido de lo que permite el presupuesto: como máximo una vez cada 86,400 × 2 / X-RateLimit-Limit segundos (17.3 segundos con el valor predeterminado de 10,000), para que las consultas usen como máximo la mitad de las llamadas del día. Consultar cada 10 segundos consume por sí solo 8,640 llamadas y deja unas 1,300 para todo lo demás; dos copias de un bot que hagan eso con una misma clave serán rechazadas antes de que termine el día.
  • Lee un borrador individual solo cuando necesites sus líneas, es decir, cuando su updatedAt cambió en la lista, y como máximo una vez por minuto por borrador. No consultes cada borrador por separado.
  • Vigila X-RateLimit-Remaining. Cuando baje de una décima parte de X-RateLimit-Limit, consulta con menos frecuencia. Recuerda que se comparte con las demás claves de la multifirma.
  • Ante un 429: espera los segundos de Retry-After, más un pequeño retraso aleatorio, y luego reintenta. No reintentes antes: la respuesta será la misma. Con key_day o multisig_day, conserva tu cursor y reanuda después de X-RateLimit-Reset.
  • Ante un 503: con Retry-After, espera ese tiempo más un valor aleatorio de 0 a 30 segundos; sin él, retrocede de forma exponencial desde 30 segundos hasta 10 minutos.
  • Ante un error de red o un 500 durante POST /drafts: vuelve a enviar la misma solicitud con el mismo clientRequestId (sección 6.2.2), tras una espera como la anterior.
  • Ante un 401: deja de usar la clave y avisa a una persona. Reintentar con una clave rechazada nunca sirve, y más de 200 fallos en un día bloquean tu dirección durante 24 horas para toda clave no válida (tus claves válidas siguen funcionando desde ella, sección 10.1).
  • Prevé la medianoche UTC: una clave o multifirma que agotó las llamadas del día queda rechazada hasta las 00:00 UTC. Reanuda entonces tras un valor aleatorio de 0 a 30 segundos, no en el segundo exacto.

11. Recomendaciones de seguridad

  • Solo HTTPS. Nunca envíes una clave por HTTP sin cifrar; si ocurrió, revoca la clave. Verifica el certificado del servidor como de costumbre.
  • Guarda la clave en tu servidor, en un almacén de secretos. Nunca en un navegador, una app móvil, un repositorio, una línea de log, una URL, un ticket o un mensaje de chat. Ownbit nunca te la pide.
  • Dale a cada clave una lista de IP permitidas IPv4 con las direcciones de salida fijas de tus servidores. Así, una clave filtrada no se puede usar en ningún otro lugar, de modo que no puede enviar borradores ni gastar las llamadas diarias de tu multifirma. Prefiere una dirección de salida dedicada a un NAT compartido o a una salida de nube: una dirección retenida o bloqueada sigue atendiendo a tus claves válidas, y una clave cuya lista de IP permitidas contiene la dirección no es rechazada por los límites por dirección de 600 por minuto o 50,000 al día, pero el límite de ráfaga y los 200,000 al día se comparten con todos los que usan la dirección (sección 10.1).
  • Una clave por sistema, con un nombre que diga cuál. Como máximo 5 claves por multifirma.
  • Rota la clave antes de que caduque y ante cualquier duda: pide a un miembro que cree una clave nueva, cambia tu bot a ella y luego revoca la anterior. Una clave nueva debe usar clientRequestIds nuevos (sección 6.2.2).
  • Ante una filtración, revoca de inmediato, en la consola web o en la app de Ownbit. Revocar rechaza los borradores de la clave que nadie ha iniciado. Si una clave filtrada agotó las llamadas de hoy de tu multifirma, la clave de reemplazo comparte ese tope hasta las 00:00 UTC: pide ayuda al soporte de Ownbit, que puede aumentar el tope de esa multifirma por ese día.
  • Desactiva los procesos que usan claves revocadas: sus fallos cuentan contra tu dirección.
  • Muestra el clientRequestId y la huella en tu canal de aprobación; comprueba contentHash y los pagos de la multifirma en la cadena (sección 8).
  • Envía symbol en cada línea.
  • Trata el texto de la API como datos, nunca como HTML ni como comandos, en tus logs y paneles.

12. Fuera de la fase 1

Webhooks; resultados de transacción por línea (identificador de transacción, hash, firmas y errores de una línea); multifirmas en otras cadenas y otros tokens; acceso por IPv6 y entradas IPv6 en la lista de IP permitidas; límites de llamadas por clave definidos por ti; borradores firmados con tu propia clave. Consulta a Ownbit si necesitas alguno de ellos.

Última actualización:

Descargar

Descargar Ownbit

Instala la app y luego configura una cartera fría o multifirma según lo que necesites.