API REST nativa

La API nativa es la interfaz REST propia de blockwallets: facturas con precio en centavos de dólar, un ref idempotente por pedido, cuentas de depósito estáticas que cubren todas las redes y webhooks firmados con HMAC-SHA256. Crea las mismas facturas en la misma página de pago alojada que la API compatible con Cryptomus, con las mismas comisiones y el mismo saldo.

Genera tus claves tú mismo en el panel, en “Desarrolladores › Integración y claves”: una clave Live y una Test con sus claves de firma de webhooks. Cada una se muestra una sola vez; la lista solo muestra su prefijo. Si tu cuenta tiene la verificación en dos pasos activada, generar o rotar una clave Live pide un código. ¿Aún no tienes cuenta de comercio? Solicita acceso. ¿Ya usas Cryptomus? Consulta la API compatible con Cryptomus (cómo elegir).

Claves y peticiones

URL base https://blockwallets.io. Las peticiones y respuestas son JSON. Cada petición lleva:

• Authorization: Bearer bw_live_… o Bearer bw_test_…: el prefijo decide el modo, así que una clave Test solo ve facturas Test y funciona en testnets
• Content-Type: application/json en las peticiones POST
• Guarda las claves solo en tu servidor, nunca en una página web ni en una app; nosotros solo almacenamos su hash

Los errores devuelven un estado HTTP y {"error": {"code": "…", "message": "…"}}: 400 invalid_request (un campo ausente o mal formado), 401 unauthorized (clave ausente, desconocida o desactivada), 404 not_found, 409 conflict (la petición choca con el estado actual de la factura), 422 currency_unsupported.

Endpoints

Añade ?probe=1 a la consulta de una factura o de una cuenta de depósito para comprobar la cadena en el momento (como máximo una vez cada 10 segundos); si no, obtienes el último estado de nuestro escáner, que revisa cada minuto.

Crear una factura POST /v1/invoices

Llama a POST /v1/invoices cuando el cliente haga el pedido y redirígelo a la pay_url de la respuesta.

curl -X POST https://blockwallets.io/v1/invoices \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"order_1042","amount":4200,"title":"Order #1042",
       "return_url":"https://shop.example/cart","success_url":"https://shop.example/thanks?order=1042",
       "meta":{"user_id":42}}'

Cada URL debe estar en uno de los dominios de tu sitio web (panel → “Desarrolladores › Integración y claves”). La respuesta es el objeto factura de abajo; network, address y pay_amount se rellenan cuando se elige una red.

El objeto factura

Los ids empiezan por inv_. amount está en centavos de dólar; pay_amount y paid_amount son importes de la moneda, como cadenas decimales, en la red elegida.

{
  "id": "inv_01J8…",
  "ref": "order_1042",
  "mode": "live",
  "status": "pending",
  "amount": 4200,
  "currency": "USD",
  "title": "Order #1042",
  "meta": { "user_id": 42 },
  "network": null,
  "address": null,
  "pay_amount": null,
  "paid_amount": null,
  "payments": [],
  "pay_url": "https://blockwallets.io/pay/inv_01J8…",
  "return_url": "https://shop.example/cart",
  "success_url": "https://shop.example/thanks?order=1042",
  "created_at": "2026-11-03T08:00:00.000Z",
  "expires_at": "2026-11-03T09:00:00.000Z",
  "paid_at": null,
  "closed_at": null
}

Otros campos: pay_url (la página de pago alojada), payments (cada transferencia con txid, amount, confirmations y confirmed), expires_at, paid_at, closed_at; BTC, LTC, DOGE, BCH y las monedas nativas también incluyen rate (dólares por moneda, bloqueada durante 30 minutos), rate_locked_until y paid_cents (lo recibido hasta ahora, en centavos de dólar).

Redes

Pasa el id como network. GET /v1/networks devuelve las abiertas ahora mismo en tu modo; una red puede estar en pausa, así que es mejor consultarla que fijarla en el código.

Cuentas de depósito (direcciones estáticas) POST /v1/deposit-accounts

POST /v1/deposit-accounts con {"customer_ref": "user_42"} da a ese cliente una dirección permanente en cada red (todas las cadenas EVM comparten una dirección). Todo lo que envíe se acredita en dólares estadounidenses, con un webhook deposit.credited por transferencia.

curl -X POST https://blockwallets.io/v1/deposit-accounts \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"customer_ref":"user_42"}'

{
  "id": "dac_01J8…",
  "mode": "live",
  "customer_ref": "user_42",
  "deposit_url": "https://blockwallets.io/deposit/dac_01J8…",
  "min_amount": 100,
  "currency": "USD",
  "networks": [
    { "id": "USDT_TRC20", "chain": "tron", "token": "USDT", "address": "TXy4…8kQ2", "min_amount": 100, "confirmations": 1, … },
    { "id": "USDC_BASE", "chain": "base", "token": "USDC", "address": "0x5aE1…", "min_amount": 100, "confirmations": 20, … }
  ]
}

• customer_ref: 1–128 caracteres entre letras, dígitos y _ . : @ -; el mismo valor devuelve siempre la misma cuenta. return_url opcional en tus dominios
• La respuesta incluye deposit_url (una página alojada con las direcciones, los códigos QR y los depósitos recientes) y networks (id, address, min_amount y confirmations de cada una)
• Los ids de depósito empiezan por dep_; amount está en centavos de dólar, amount_token es el importe en la moneda y las monedas con precio incluyen la rate usada

Las transferencias por debajo del mínimo (normalmente $1, BTC $5) se registran como below_min y no se acreditan automáticamente; contáctanos para que las acreditemos.

Webhooks

Enviamos un POST con JSON a la URL de webhook del panel (“Desarrolladores › Integración y claves”; Live y Test tienen cada uno su propia URL y su propio secret). El cuerpo es el evento:

POST /your/webhook
X-BW-Event: ev_01J8…
X-BW-Delivery: 1
X-BW-Signature: t=1793693052,v1=5f0c9b…

{"id":"ev_01J8…","type":"invoice.paid","created_at":"2026-11-03T08:04:12.000Z","invoice":{"id":"inv_01J8…","ref":"order_1042","status":"paid","amount":4200,…}}

• X-BW-Signature: t=<unix seconds>,v1=<hex>, donde v1 = HMAC-SHA256(webhook secret de ese modo, t + . + cuerpo sin procesar)
• X-BW-Event: el id del evento (ev_…); deduplica por él
• X-BW-Delivery: el número de intento, empezando en 1

Verifica contra el cuerpo sin procesar antes de analizarlo, rechaza una t que difiera más de 300 segundos de tu reloj y compara en tiempo constante. invoice / deposit en el cuerpo es el mismo objeto que devuelve una consulta.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), header: X-BW-Signature
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return typeof parts.v1 === "string" && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Una respuesta 2xx cuenta como entregada; si no, reintentamos tras 1 minuto, 5 minutos, 30 minutos, 2 horas, 12 horas, 24 horas y 24 horas (8 intentos en total).

Eventos y reenvío

GET /v1/events?invoice_id=inv_… (o deposit_id=dep_…) lista los webhooks de una factura o un depósito con su state, attempts, last_status y last_error. POST /v1/events/ev_…/redeliver lo pone de nuevo en cola al instante, por ejemplo después de corregir tu endpoint. La página “Desarrolladores › Registro de webhooks” del panel muestra cada intento con su petición y su respuesta.

Modo de prueba

Las facturas creadas con una clave bw_test_ funcionan en testnets y nunca tocan dinero real. La página de pago alojada muestra un botón “Simular pago” (completo / mitad / de más), así que puedes ver los estados y los webhooks sin monedas de testnet.