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:
| Llamada | Permiso | Qué hace |
|---|---|---|
GET /whoami | drafts:read | Describe la clave y su multifirma, con los recuentos de llamadas del día |
POST /drafts | drafts:submit | Enví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 /drafts | drafts:read | Lista los borradores de esta clave, del cambio más antiguo al más reciente, con un cursor |
GET /drafts/{draftId} | drafts:read | Lee un borrador con sus líneas |
DELETE /drafts/{draftId} | drafts:submit | Retira un borrador que nadie ha iniciado |
2. Alcance de la fase 1
- Solo multifirmas en TRON. Las líneas pagan en
TRXoUSDT(USDT-TRC20, contratoTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t); ambos tienen 6 decimales. - Solo IPv4. A la API solo se accede por IPv4 (
api.bittool.comno 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_requiredy nunca se redirige. Una clave que se haya enviado por HTTP sin cifrar debe considerarse filtrada: revócala y crea otra. Las respuestas HTTPS llevanStrict-Transport-Security: max-age=31536000. - JSON en UTF-8. Las solicitudes
POSTenvíanContent-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-cacheyX-Request-Id(req_seguido de 16 caracteres de[0-9a-z]). Los cuerpos de error lo repiten comorequestId. 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, comoobk_…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
/8a/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:submitydrafts: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_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgNunca 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
401no 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 sinsymbol. En una multifirma de TRON esTRX, noUSDT: envíasymbolen cada línea (sección 6.2).requiredNumdeownerNum: 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"]}| Campo | Regla |
|---|---|
clientRequestId | De 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) |
lines | De 0 a 500 objetos, cada uno solo con las claves siguientes. La primera llamada debe enviar al menos uno |
remove | Opcional. 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 |
lineId | Obligatorio. 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 |
to | Una 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) |
amount | Una 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") |
symbol | TRX 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) |
memo | Opcional. 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:
| Estado | Cuerpo | Cuá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_editable | details.draftId, details.status | El borrador ya no está en submitted (un firmante lo inició, o fue retirado, rechazado o caducó): no cambió nada |
409 idempotency_conflict | Otra clave de la misma multifirma ya usó el clientRequestId | |
410 gone | El borrador de este clientRequestId se eliminó (conservación, sección 7.3) | |
422 invalid_lines | details.errors | Una o más líneas no son válidas, o el borrador quedaría vacío; no cambió nada |
429 daily_limit | details.scope | Se 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 porlineId).memoes""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:truecuando 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 unanotede una línea),phone(un firmante lo rechazó en su teléfono; sinnote) ykey_revoked. La API nunca dice qué miembro lo rechazó.
6.2.2 Reintentos y cambios
clientRequestIdidentifica 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 recibe409 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 responde409 not_editable: pide a los firmantes que rechacen las líneas que no se deben pagar y envía las nuevas con unclientRequestIdnuevo. - 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
| Estado | Significado |
|---|---|
submitted | Nadie lo ha iniciado todavía. Solo en este estado tu bot puede modificarlo (sección 6.2) o retirarlo (sección 6.5) |
started | Un 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 |
rejected | Un 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 |
withdrawn | Tu bot lo retiró |
expired | Nadie 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.
| Estado | Significado |
|---|---|
pending | El borrador está en submitted |
started | El borrador está en started |
rejected, withdrawn, expired | El 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:
- Muestra el
clientRequestIdy la huella (los primeros 16 caracteres hexadecimales decontentHash) 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. - 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. - 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 (enwhoami, el campomultisig.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. - 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. - 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.
| HTTP | code | Cuándo |
|---|---|---|
| 400 | invalid_request | No 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 |
| 401 | unauthorized | Cualquier problema con la clave (sección 5) |
| 403 | forbidden | Una clave válida sin el permiso de la llamada |
| 403 | https_required | La solicitud no llegó por HTTPS (revoca la clave que llevaba) |
| 404 | not_found | Una ruta desconocida; un borrador que no es de esta clave o que ya no se conserva |
| 405 | method_not_allowed | Un método que la ruta no acepta (incluido OPTIONS) |
| 409 | idempotency_conflict | Sección 6.2 |
| 409 | not_editable | Sección 6.2 (details.status) |
| 409 | not_withdrawable | Sección 6.5 (details.status) |
| 410 | gone | Un clientRequestId cuyo borrador se eliminó |
| 413 | too_large | Un cuerpo de más de 256 KiB |
| 415 | unsupported_media_type | Un POST que no es JSON |
| 422 | invalid_lines | Sección 6.2 (details.errors) |
| 429 | rate_limited, daily_limit | Un límite (sección 10), con Retry-After, details.scope, details.limit, details.retryAfter |
| 500 | internal | Un error del lado de Ownbit; reintenta más tarde |
| 503 | unavailable | La 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ímite | Valor | details.scope | code |
|---|---|---|---|
| Solicitudes desde una dirección, ráfaga | 20 por segundo (ráfagas de hasta 40), 20 conexiones abiertas | edge | rate_limited |
| Llamadas por clave | 10 por segundo | key_second | rate_limited |
| Llamadas por clave | 300 por minuto | key_minute | rate_limited |
POST /drafts por clave | 60 por hora | key_submit_hour | rate_limited |
| Llamadas en curso a la vez, por clave | 2 | key_concurrent | rate_limited |
| Llamadas en curso a la vez, por multifirma (todas sus claves) | 4 | multisig_concurrent | rate_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ón | ip_minute | rate_limited |
| Llamadas por clave | 10,000 al día | key_day | rate_limited |
| Llamadas por multifirma (todas sus claves juntas) | 20,000 al día | multisig_day | rate_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ón | ip_day | rate_limited |
| Llamadas por dirección (claves válidas), tope absoluto | 200,000 al día, para todas las claves | ip_day (details.limit 200000) | rate_limited |
| Llamadas fallidas por dirección | 20 por minuto; si se supera, la dirección queda retenida 10 minutos | ip_failures | rate_limited |
| Llamadas fallidas por dirección | 200 al día; si se supera, la dirección queda bloqueada 24 horas | ip_blocked | rate_limited |
| Llamadas fallidas por red (una /24) | 1,000 al día; si se supera, la red queda bloqueada 24 horas | net_blocked | rate_limited |
| Líneas de pago por clave | el límite propio de la clave (de 1 a 10,000; 1,000 de forma predeterminada) en cualquier periodo de 24 horas | key_lines_24h | daily_limit |
| Líneas de pago por multifirma | 10,000 en cualquier periodo de 24 horas | multisig_lines_24h | daily_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,422o el429de un límite de líneas) y unPOST /draftsrepetido. Una llamada rechazada por un límite de solicitudes o un tope no cuenta para ninguno de ellos, así que esperar lo que indicaRetry-Aftersiempre 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
429con alcanceip_minuteoip_dayte 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:
| Cabecera | Valor |
|---|---|
X-RateLimit-Limit | El tope diario de llamadas de la clave (10000) |
X-RateLimit-Remaining | Lo que queda hoy después de esta llamada: el menor entre lo que les queda a la clave y a su multifirma |
X-RateLimit-Reset | Las 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 últimonextCursorentre reinicios; una página vacía lo devuelve sin cambios. CuandohasMoreestrue, 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-Limitsegundos (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
updatedAtcambió 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 deX-RateLimit-Limit, consulta con menos frecuencia. Recuerda que se comparte con las demás claves de la multifirma. - Ante un
429: espera los segundos deRetry-After, más un pequeño retraso aleatorio, y luego reintenta. No reintentes antes: la respuesta será la misma. Conkey_dayomultisig_day, conserva tu cursor y reanuda después deX-RateLimit-Reset. - Ante un
503: conRetry-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
500durantePOST /drafts: vuelve a enviar la misma solicitud con el mismoclientRequestId(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
clientRequestIdy la huella en tu canal de aprobación; compruebacontentHashy los pagos de la multifirma en la cadena (sección 8). - Envía
symbolen 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 Ownbit
Instala la app y luego configura una cartera fría o multifirma según lo que necesites.