api completa para dólar digital.

qué significa "completa"

casi todos los equipos empiezan con una sola necesidad, por lo general "mostrar una dirección de depósito en el checkout". un mes después están manteniendo un nodo, un indexador, una billetera de gas por red y una planilla para conciliar todo. estas son las tareas que aparecen tarde o temprano:

alrededor están las llamadas pequeñas que evitan tickets de soporte: POST /address/validate y POST /address/detect antes de pagar, GET /balance/{red}/{dirección}/{token} para el saldo en vivo y GET /quote para la comisión exacta antes de mover nada.

del registro a la primera dirección

crea la cuenta en el panel con Google, GitHub o un código por correo. la primera clave (dr_live_...) se emite ahí, en el plan free, y va en el encabezado X-Api-Key de cada llamada. la URL base es https://api.dolaramp.com/v1.

1. crea una hotwallet, una por red:

curl https://api.dolaramp.com/v1/hotwallets \
  -H "X-Api-Key: dr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"network":"base","label":"acme main"}'

la respuesta trae un wallet_secret (ws_...) una sola vez. cifra la clave de la hotwallet y de todas las direcciones hijas; nosotros guardamos solo el texto cifrado. sin él, ni dolaramp puede mover los fondos, así que guárdalo fuera del servidor de la aplicación. en Base y Arbitrum la hotwallet es una sola dirección, válida en las dos redes.

2. genera una dirección de depósito y márcala con tu propio identificador:

curl https://api.dolaramp.com/v1/hotwallets/base/children \
  -H "X-Api-Key: dr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"wallet_secret":"ws_...","count":1,"external_refs":["order-10432"]}'

hasta 100 direcciones hijas por llamada. el external_ref es tuyo: número de pedido, id de usuario, comercio:cobro. vuelve en cada depósito, y acreditas al cliente correcto sin consulta extra.

en camino no es confirmado

esta es la parte que cuesta dinero cuando sale mal. un depósito tiene dos momentos:

• en camino (arriving): la transferencia fue vista en la red. significa "existe una transacción", no "no tiene vuelta atrás". webhook deposit.detected.
• confirmado (confirmed): se cumplió la regla de la propia red. webhook deposit.confirmed. libera el pedido aquí, nunca antes.

un depósito que no liquida dentro del plazo dispara deposit.abandoned: trátalo como no recibido.

los webhooks van solo por HTTPS, con hasta 8 intentos en intervalo creciente (30 segundos, luego duplicando) y firma HMAC-SHA256. el secreto se muestra una vez, cuando registras el endpoint en POST /webhooks. la firma llega en el encabezado X-DolaRamp-Signature, como el HMAC en hexadecimal del cuerpo sin procesar. verifícala antes de creer en el contenido:

import { createHmac, timingSafeEqual } from 'node:crypto';

function isFromDolaramp(rawBody, header, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

calcúlala sobre los bytes que llegaron, no sobre un JSON reconstruido. si tu cola se cayó, GET /webhooks/deliveries muestra lo que se envió y GET /deposits entrega los mismos datos por consulta.

barrido y retiro, sin tanque de gas

el dolor clásico de las direcciones de depósito: para sacar 20 USDT de una dirección hija, esa dirección necesita la moneda de la red. multiplica por unos miles de direcciones y tienes una operación de gas que mantener. aquí el gas está patrocinado y la comisión sale de dentro de la transferencia, en stablecoin.

POST /sweep junta las direcciones hijas en la hotwallet por lote: por defecto las 20 más recientes, o hasta 20 que indiques en child_addresses. en Solana, gram(TON), Base y Arbitrum responde confirmed con el tx_hash. en TRON responde accepted en 1 a 2 segundos y la confirmación llega por webhook (sweep.confirmed).

un pago es una llamada:

curl https://api.dolaramp.com/v1/hotwallet/withdraw \
  -H "X-Api-Key: dr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"network":"base","token":"USDC","to":"0x...","amount":"10000000",
       "wallet_secret":"ws_...","idempotency_key":"payout-inv-10432"}'

amount va en microunidades (6 decimales), así que 10000000 son 10 USDC, y quien recibe obtiene el monto menos la comisión. tres comportamientos que conviene conocer antes de producción:

• idempotencia. repite con la misma idempotency_key y vuelve la operación original, con replayed: true. un timeout seguido de un reintento nunca paga dos veces.
• sin pago parcial silencioso. un retiro mayor que el saldo se rechaza con 400 insufficient_balance. en TRON puedes enviar allow_partial: true para mandar lo que alcance.
• 202 pendiente. si la transferencia se entregó a la red pero su llegada no se vio a tiempo, la llamada responde 202 con status: pending. el resultado llega como withdraw.confirmed o withdraw.failed, por lo general en menos de un minuto.

mover usdc entre redes

POST /bridge mueve USDC entre Solana, Base y Arbitrum por el CCTP de Circle: se quema en el origen y Circle lo emite en el destino, uno a uno. es un cambio de red, no un intercambio: sin pool, sin slippage. la vía rápida tarda de 8 a 20 segundos. el tope es de US$ 10.000.000 por operación y el monto mínimo es US$ 10.

GET /bridge/quote detalla la operación antes de ejecutarla: nuestra comisión, la de Circle (trasladada sin recargo) y cuánto llega al destino. la historia completa, con tiempos medidos, está en mover USDC de Solana a Base.

cuánto cuesta

el plan free no tiene mensualidad, y recibir es gratis en todos los planes. pagas por barrido o retiro, en stablecoin, dentro de la operación:

el plan free vigila 1.000 direcciones y el pro, 50.000. el puente cuesta US$ 2 + 0,3% en free y US$ 2 + 0,2% en pro.

dos costos que sorprenden: la primera salida de una dirección nueva en Solana también paga sus cuentas de token (~US$ 0,65 en free), y una dirección inactiva en TRON paga una activación única de 1,50 USDT. si tus clientes pagan por TRON, prefiere una dirección fija por cliente a una dirección desechable por pedido. de dónde sale ese 1,50 está en enviar USDT sin TRX.

valores de pricing a precios del 25/09/2026. Solana y gram(TON) siguen el precio de SOL y TON. GET /v1/quote devuelve la comisión exacta de tu plan.

lo que la api no hace

mejor saberlo antes de diseñar el sistema sobre ella:

• no maneja moneda local. dolaramp no convierte divisas, no guarda saldo bancario ni envía transferencias bancarias. la parte en moneda local pasa por un exchange o proveedor de pagos con licencia. GET /rates da una referencia de mercado del USDT frente a monedas locales; no es una cotización ejecutable, así que aplica tu propio spread.
• no cambia un token por otro. USDT no se vuelve USDC aquí. el puente mueve el mismo activo, USDC, entre redes.
• no hay puente para TRON ni gram(TON). el puente cubre solo Solana, Base y Arbitrum.
• una hotwallet por red, y 20 direcciones hijas por llamada de barrido. para miles, hazlo en bucle.
• límite de uso: 120 solicitudes por minuto por clave.
• no hay red de prueba. la API corre en las redes reales. una forma barata de ensayar es usar unos pocos dólares de USDC en Base, donde la operación cuesta US$ 0,10.

claves y seguridad

cada clave de API tiene un alcance: read (listar, cotizar, consultar) u operate (todo, incluidos barrido, retiro y puente). una escritura con clave read responde 403 insufficient_scope, así que los paneles y reportes pueden funcionar con una clave que no mueve dinero. la clave también puede limitarse a IPs específicas.

el modelo de custodia es el punto central: las claves de la hotwallet quedan en un sobre que solo se abre con tu wallet_secret, y toda llamada que mueve fondos tiene que llevar ese secreto. más en security.

los siete perfiles de integración (tienda, gateway, exchange, solo entrada, solo salida, pagos masivos, tarjeta cripto) están dibujados llamada por llamada en los flujos de integración, y cada endpoint está en la referencia de la API.

preguntas frecuentes