Bitcoin API: Acepta Pagos en BTC Sin Ejecutar un Node

El JSON-RPC de Bitcoin Core quiere un nodo sincronizado antes de la primera respuesta útil. Una REST API quiere una API key. La diferencia se nota en tu calendario: la descarga inicial del bloque tarda días en hardware típico, y después el nodo consume disco y ancho de banda, y sigue necesitando monitorización, durante todo el tiempo que viva tu producto. Nuestro artículo sobre blockchain API vs. blockchain node compara ambos enfoques en detalle. Ejecuta tu propio nodo cuando necesites control a nivel de política sobre tu visión de la red; usa la API cuando el objetivo sean los pagos.

Las llamadas del día a día se ajustan limpiamente al modelo REST. Donde una integración de nodo envuelve getnewaddress y listtransactions y hace polling en busca de cambios, la API asigna direcciones y deja que el webhook se encargue de vigilar. Los bucles de polling desaparecen, y con ellos los cron jobs que se rompen en silencio un fin de semana.

Hay una segunda diferencia. Los métodos RPC en bruto devuelven datos en bruto. Chaingateway devuelve JSON estructurado con campos legibles, así que una respuesta puede ir directamente a tu base de datos en lugar de pasar por una capa de parseo.

El lado REST de la ruta de envío son tres endpoints. POST /api/v2/bitcoin/wallets crea una wallet, cifrada con una contraseña que Chaingateway no almacena — piérdela y nadie puede restaurar la wallet, que es precisamente el objetivo. POST /api/v2/bitcoin/wallets/{wallet}/addresses deriva tantas direcciones bajo ella como necesites; una wallet las lleva todas. Y POST /api/v2/bitcoin/transactions envía:

curl -X POST https://app.chaingateway.io/api/v2/bitcoin/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "amount": 0.0015,
    "walletname": "treasury",
    "password": "wallet-password",
    "speed": "medium"
  }'

La respuesta lleva el txid de la transacción transmitida. speed acepta fast, medium o slow y fija el nivel de comisión — la disyuntiva entre coste y tiempo hasta la primera confirmación. Un subtractfee: true opcional deduce la comisión de red del importe en lugar de añadirla encima, que es lo que quieres cuando un cliente retira todo su saldo.

Bitcoin añade un bloque aproximadamente cada diez minutos, aunque los intervalos individuales varían mucho. Cada bloque nuevo minado sobre el que contiene tu transacción añade una confirmación, y cada confirmación hace la reversión más difícil.

Seis confirmaciones — aproximadamente una hora — ha sido el estándar de facto para "liquidado" desde los primeros días de los exchanges, y sigue siendo así a mediados de 2026.

Diez minutos es un promedio, no un horario

El ajuste de dificultad lo mantiene a lo largo del tiempo, pero los intervalos individuales se dispersan mucho a su alrededor — dos bloques en un minuto suceden, y también sequías de cuarenta minutos. La experiencia de usuario en pagos tiene que respetar esto: "unos diez minutos" es un promedio, no una promesa, así que tu página de checkout debería decir "normalmente en menos de una hora" en lugar de mostrar un temporizador de cuenta regresiva que no puede cumplir.

¿Por qué no acreditar con cero confirmaciones?

Porque hasta que una transacción está en un bloque, permanece en el mempool, donde puede ser reemplazada o gastada doblemente, e incluso el bloque más reciente puede salir de la chain en una reorganización. La API divide ese trabajo en dos. El webhook se dispara una vez que la transacción se liquida on-chain — el payload lleva importe, dirección, txid y número de bloque — así que tu interfaz puede reaccionar de inmediato. A partir de ahí, GET /api/v2/bitcoin/transactions/{txid}/decoded devuelve el recuento de confirmaciones actual, así que tu contabilidad solo acredita dinero que ha alcanzado tu umbral. Muestra el progreso pronto, liquida tarde.

Bitcoin no tiene saldos de cuenta. Lo que la chain almacena son unspent transaction outputs — UTXOs — cada uno un bulto discreto de valor bloqueado a una dirección. El "saldo" de una wallet es un número que tu software deriva sumando cada UTXO que controlan sus direcciones; el protocolo nunca almacena esa suma en ningún sitio. Gastar consume UTXOs enteros y crea otros nuevos, incluida una salida de cambio de vuelta a ti mismo, de la misma forma en que pagar una factura de 7 euros con un billete de 10 devuelve monedas.

Ethereum funciona con el modelo opuesto. Una cuenta tiene un saldo, la chain lo almacena directamente, y un depósito es un incremento. En las EVM chains es normal dar a un cliente una única dirección y dejar que se acumulen cien depósitos sobre ella a lo largo de los años.

Para el manejo de depósitos, el modelo UTXO tiene una ventaja práctica: te empuja hacia una dirección por cliente o por factura, que es de todas formas el diseño más limpio. Cada pago entrante es una salida nueva hacia una dirección que observas, así que la atribución es inequívoca — sin parsear memos, sin emparejar por importe. También significa que "el saldo de una dirección" es una pregunta que responde un indexador y no la chain, que es precisamente la contabilidad que subcontratas al usar una API con webhooks en lugar de ejecutar la maquinaria tú mismo. La notificación te dice: este importe, esta dirección, esta transacción, este bloque. El resto lo hace tu contabilidad.

Añade la cabecera X-Network: testnet y cada llamada de esta página se ejecuta contra la red de pruebas de Bitcoin: mismas rutas, mismas formas de respuesta, monedas sin valor. Los faucets reparten BTC de prueba gratis, así que todo el flujo de depósito — dirección, pago, webhook, confirmaciones — se puede ensayar de principio a fin sin gastar un satoshi.

Mantén la cabecera detrás de la configuración en lugar de esparcida por el código, y da a tu entorno de staging una URL de callback separada para que los depósitos de prueba no puedan filtrarse a la contabilidad de producción. Cuando el ensayo funcione, elimina la cabecera. Nada más de la integración cambia, que es la clave: el primer depósito en mainnet debería ser aburrido.

Un backend de pagos se gana el sueldo en los días malos, así que planifica las rutas de fallo de forma explícita.

En la capa HTTP las reglas son las de REST estándar. Un 401 significa que el Bearer token está mal o ausente; corrige la key en lugar de reintentar. Otras respuestas 4xx apuntan a la solicitud en sí — registra el cuerpo, que nombra el problema, y trátalo como un error, no como algo que reintentar. Las respuestas en el rango 5xx y los timeouts son transitorios; reintenta esos con backoff.

Los modos de fallo específicos de Bitcoin viven por encima de HTTP. Un depósito que nunca confirma normalmente pagó muy poca comisión y está atascado en el mempool; puede confirmar horas después o desaparecer por completo, razón por la cual detected y settled deben permanecer como estados separados en tu sistema. Una notificación por un importe inferior a la factura es una decisión de negocio, no un error — gestiónala en código, no en una cola de soporte. Y si tu endpoint de webhook estuvo caído, las entregas fallidas te esperan: GET /api/v2/bitcoin/webhooks/notifications/failed las lista, POST /api/v2/bitcoin/webhooks/notifications/{id}/retry reenvía cada una, y la lista completa en GET /api/v2/bitcoin/webhooks/notifications te permite comparar con la contabilidad y acreditar las brechas. Ejecuta esa comparación cada noche aunque nada parezca ir mal. Una conciliación que solo se ejecuta tras un incidente encuentra sus errores en producción.

Bitcoin en sí no tiene USDT ni USDC — las stablecoins viven en otras chains. Lo que la plataforma compartida te da es una ventaja: tu integración de Bitcoin ya habla la misma API que nuestros endpoints de Ethereum y TRON. Acepta BTC hoy, añade USDT en TRON el próximo sprint con la misma key y el mismo manejador de webhook. La visión general de la blockchain API lista las siete chains soportadas.

El orden práctico para la mayoría de equipos: lanza primero los depósitos en BTC, porque eso es lo que los clientes piden por nombre, y luego deja que los datos de pago te digan qué riel de stablecoin añadir en segundo lugar. En Chaingateway, ese segundo riel reutiliza tu verificación de firma, tu trabajo de conciliación y tu máquina de estados de depósito sin cambios.

• Tiene el historial más largo de cualquier blockchain, en funcionamiento desde 2009, y el mayor reconocimiento entre los usuarios finales.
• La red liquida las 24 horas. No hay horario bancario ni cortes regionales.
• Las confirmaciones siguen un ritmo predecible, con un bloque nuevo aproximadamente cada diez minutos, lo cual mantiene fáciles de razonar los flujos de pago.
• La adopción es la mayor de todas las redes cripto, así que "¿aceptáis Bitcoin?" sigue siendo la primera pregunta que hacen los clientes.

Ninguna de estas propiedades salió de una actualización de roadmap; son las mismas garantías con las que se lanzó la red. Esa estabilidad es el argumento a favor de BTC en productos con horizontes largos: una integración construida este año no quedará obsoleta por un giro de protocolo el año que viene, que es más de lo que puede decir la mayoría de las pilas de pago.

El caso obvio es el checkout: un cliente elige Bitcoin y tu aplicación asigna una dirección; el webhook confirma el pago. Los mismos bloques de construcción soportan también cargas más pesadas. Los exchanges y las plataformas de gaming ejecutan una dirección de depósito por usuario y acreditan saldos al confirmar. Los flujos de pago y remesas empujan transferencias transfronterizas sin bancos corresponsales en medio. Los negocios de suscripción generan una dirección de factura nueva cada ciclo y dejan que el webhook la cierre.

Lo que comparten estos casos es la forma del trabajo. Bitcoin gestiona la liquidación; tu aplicación gestiona el estado. La API se sitúa entre ambos y convierte eventos de la chain en llamadas HTTP que tu framework ya sabe enrutar — razón por la cual el caso del checkout y el del exchange se ejecutan con el mismo puñado de endpoints.