TOKIIA Pay API & BeeChain WaaS — Pagos Crypto y Wallet as a Service

API v1 — Producción

Acepta pagos crypto
con TOKIIA Pay

Pasarela de pagos con stablecoins para tu negocio. Integra en minutos, cobra USDT de tus clientes, y retira a tu wallet cuando quieras.

Rápido

Integración en 10 minutos. Solo necesitas una API Key y una llamada HTTP.

Seguro

Seguridad Shamir 2-de-3 en hot wallets. Fondos protegidos a nivel criptográfico.

Multi-chain

Polygon, BSC, TRON y Ethereum. Tu cliente paga en la red que prefiera.

Autenticación

Todas las llamadas (excepto /rates) requieren tu API Key

Incluye tu API Key en el header X-API-Key de cada petición:

Header

X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx

La API Key se genera al registrarte como merchant en TOKIIA Pay. Guárdala de forma segura — no se puede recuperar.

Base URL

https://panel.tokiia.com/api/v1

Redes Soportadas

TOKIIA Pay opera en múltiples blockchains

Red	Identificador	Token	Costo por TX
Polygon PoS	`polygon`	USDT	~$0.01
TRON	`tron`	USDT TRC-20	~$0.50
BSC	`bsc`	USDT BEP-20	~$0.10
Ethereum	`ethereum`	USDT ERC-20	~$2-5

Guía Rápida

Empieza a cobrar en 6 pasos

Regístrate como Merchant

Contacta al equipo TOKIIA y obtén tu API Key (tk_live_xxx)

Crea un Invoice

Llama a POST /invoice/create con el monto a cobrar

Muestra la Dirección

Recibes una deposit_address. Tu cliente envía USDT ahí

Recibe Confirmación

TOKIIA detecta el pago on-chain y notifica via webhook

Verifica el Estado

Consulta GET /invoice/{'{'}id{'}'} para confirmar el status

Retira tus Fondos

Envía USDT a tu wallet con POST /payout/create

POST/invoice/createAPI Key

Crea un cobro. Genera una dirección de depósito donde tu cliente envía USDT. El invoice expira en 1 hora.

Parámetros del Body

amount requeridonumberMonto a cobrar en USD (mayor a 0)

currency opcionalstringMoneda de referencia. Default: "USDT"

network opcionalstringRed blockchain: polygon, tron, bsc, ethereum

description opcionalstringDescripción del cobro

external_id opcionalstringID de tu sistema para conciliar

callback_url opcionalstringURL para recibir webhook cuando el pago se confirme

metadata opcionalobjectDatos extra que recibirás en el webhook

Ejemplo — cURL

cURL

curl -X POST "https://panel.tokiia.com/api/v1/invoice/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "amount": 100.00,
    "network": "tron",
    "description": "Suscripción mensual",
    "callback_url": "https://tuapp.com/webhook"
  }'

Ejemplo — JavaScript

JavaScript

const response = await fetch('https://panel.tokiia.com/api/v1/invoice/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'tk_live_xxx'
  },
  body: JSON.stringify({
    amount: 100.00,
    network: 'tron',
    description: 'Suscripción mensual',
    callback_url: 'https://tuapp.com/webhook'
  })
});

const data = await response.json();
// data.deposit_address → mostrar al cliente para que pague

Respuesta exitosa — 201

JSON

{
  "invoice_id": "inv_abc123def456",
  "invoice_number": "INV-00001",
  "amount": 100.00,
  "coin": "USDT",
  "network": "tron",
  "deposit_address": "TNBS9rb6bGSG2YUe6CDjUccXSF7uMYALks",
  "qr_code_data": "tron:TNBS9rb6b...?amount=100&coin=USDT",
  "status": "pending",
  "expires_at": "2026-02-25T13:00:00Z",
  "created_at": "2026-02-25T12:00:00Z"
}

GET/invoice/{id}API Key

Consulta el estado de un invoice. Útil para verificar si un pago se completó.

Estados posibles

Status	Descripción
pending	Esperando pago del cliente
completed	Pago recibido y confirmado on-chain
expired	No se recibió pago antes de la expiración

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/invoice/inv_abc123" \
  -H "X-API-Key: tk_live_xxx"

POST/payout/createAPI Key

Envía USDT desde tu balance a una dirección externa. Ideal para retiros, pagos a proveedores o liquidaciones.

Parámetros del Body

amount requeridonumberMonto a enviar (mayor a 0)

destination_address requeridostringWallet destino

network opcionalstringRed blockchain. Default: red configurada del merchant

description opcionalstringDescripción del pago

Ejemplo

cURL

curl -X POST "https://panel.tokiia.com/api/v1/payout/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "amount": 50.00,
    "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD08",
    "network": "polygon"
  }'

Respuesta — 201

JSON

{
  "payout_id": "po_xyz789",
  "amount": 50.00,
  "fee": 0.75,
  "net_amount": 49.25,
  "network": "polygon",
  "destination_address": "0x742d...bD08",
  "status": "pending"
}

GET/balanceAPI Key

Consulta tu balance disponible y pendiente, desglosado por red.

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/balance" \
  -H "X-API-Key: tk_live_xxx"

Respuesta — 200

JSON

{
  "balances": [
    { "network": "polygon", "available": 1500.00, "pending": 200.00 },
    { "network": "tron", "available": 800.00, "pending": 0 },
    { "network": "bsc", "available": 350.00, "pending": 50.00 }
  ]
}

GET/transactionsAPI Key

Lista todas tus transacciones (invoices + payouts) con paginación.

Query Parameters

page opcionalnumberNúmero de página. Default: 1

per_page opcionalnumberResultados por página. Default: 25, máximo: 100

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/transactions?page=1&per_page=10" \
  -H "X-API-Key: tk_live_xxx"

POST/address/validateAPI Key

Valida si una dirección wallet es correcta para una red específica. Útil antes de crear un payout.

Ejemplo

cURL

curl -X POST "https://panel.tokiia.com/api/v1/address/validate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{ "address": "0x742d...bD08", "network": "polygon" }'

Respuesta — 200

JSON

{
  "valid": true,
  "network": "polygon",
  "format": "evm"
}

GET/ratesPúblico

Obtiene tasas de conversión actuales. No requiere autenticación.

Ejemplo

cURL

curl "https://panel.tokiia.com/api/v1/rates"

Respuesta — 200

JSON

{
  "rates": {
    "USDT": { "usd": 1.00, "usd_24h_change": 0.03 },
    "TRX":  { "usd": 0.28, "usd_24h_change": 1.07 },
    "BNB":  { "usd": 600.13, "usd_24h_change": -0.01 }
  },
  "timestamp": "2026-02-25T12:00:00Z",
  "cache_ttl_seconds": 300
}

Webhooks

Recibe notificaciones automáticas cuando un pago cambia de estado

Si incluyes callback_url al crear un invoice, TOKIIA Pay enviará un POST a esa URL cuando el pago se complete:

Webhook Payload

// POST a tu callback_url
{
  "event": "invoice.completed",
  "data": {
    "id": "inv_abc123",
    "status": "completed",
    "amount": 100.00,
    "paid_amount": 100.00,
    "tx_hash": "0xabc123...def456",
    "external_id": "order-123",
    "paid_at": "2026-02-25T11:35:00Z"
  }
}

Eventos disponibles

Evento	Descripción
`invoice.completed`	Pago recibido y confirmado on-chain
`invoice.expired`	El invoice expiró sin recibir pago
`payout.sent`	Payout enviado a la blockchain
`payout.confirmed`	Payout confirmado on-chain

Buenas prácticas

Responde con HTTP 200 en menos de 5 segundos
Verifica el pago consultando GET /invoice/{id} antes de entregar el servicio
Implementa idempotencia — podrías recibir el mismo evento más de una vez

Rate Limits

Límites por categoría de endpoint

Categoría	Límite	Endpoints
Invoices	100 req/min	/invoice/create
Payouts	50 req/min	/payout/create
Lectura	300 req/min	/balance, /transactions, /invoice/{id}, /rates

Errores

Todas las respuestas de error siguen el mismo formato

Error Response

{
  "error": "Descripción del error"
}

HTTP	Error	Causa
400	amount must be greater than 0	Monto inválido o faltante
400	destination_address is required	Falta dirección en payout
401	API key inválida	Key no enviada o incorrecta
403	Merchant no activo	La cuenta está suspendida
404	Invoice not found	El invoice no existe o no te pertenece
429	Rate limit exceeded	Demasiadas peticiones por minuto
500	Internal server error	Error del servidor — contacta soporte

BeeChain WaaSNuevo

WaaS — Wallet as a Service

Envía dinero de A a B
con BeeChain WaaS

Wallet as a Service — Ledger criptográfico interno. Crea wallets internas para tus usuarios y mueve dinero entre ellas de forma instantánea, segura y sin costo de gas. Cada transacción se registra en un ledger criptográfico con hash-chain SHA-256, verificable e inmutable.

Instantáneo

Transferencias en menos de 100ms. Sin blockchain pública, sin gas fees. $0 por transacción.

Inmutable

Hash-chain SHA-256 encadena cada TX con la anterior. Modificar una rompe toda la cadena.

Verificable

Tus usuarios pueden verificar la integridad de cualquier transacción con su tx_hash de 64 caracteres.

Comparativa

Característica	Blockchain Real	BeeChain WaaS
Costo por TX	$1-50 (gas)	$0
Velocidad	1-60 segundos	<100ms
Criptografía	SHA-256/Keccak	SHA-256 + HMAC
Inmutable	Sí (consenso)	Sí (hash chain)
Reversible	Nunca	Admin puede (queda registro)
Almacenamiento	Red pública	Supabase + Cloudflare R2

Casos de uso

Billeteras internas para tu app/plataforma
Remesas y transferencias P2P
Pagos entre usuarios dentro de tu ecosistema
Programas de recompensas y cashback
Marketplaces con balance interno

Autenticación WaaS

Usa la misma API Key de TOKIIA Pay

BeeChain WaaS comparte la misma autenticación que TOKIIA Pay. Incluye tu API Key en el header X-API-Key:

Header

X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://panel.tokiia.com/api/v1/waas

Ejemplo

cURL

curl -H "X-API-Key: tk_live_xxxxx" \
  "https://panel.tokiia.com/api/v1/waas/balance?email=alice@mail.com"

Nota: Tu merchant debe tener WaaS habilitado. Contacta soporte@tokiia.com para activarlo.

Guía Rápida — 5 minutos

De cero a transferencias en 5 pasos

Obtén tu API Key

Usa la misma API Key de TOKIIA Pay (tk_live_xxx)

Crea una Wallet

POST /waas/wallets con el email del usuario

Deposita Fondos

POST /waas/deposit para cargar balance inicial

Transfiere entre Usuarios

POST /waas/transfer de un email a otro

Consulta Balances

GET /waas/balance para ver el saldo de cualquier usuario

Ejemplo completo — JavaScript

JavaScript

const API_KEY = 'tk_live_xxxxx';
const BASE = 'https://panel.tokiia.com/api/v1/waas';

// 1. Crear wallet para Alice
const alice = await fetch(`${BASE}/wallets`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
  body: JSON.stringify({ email: 'alice@tuapp.com', display_name: 'Alice' })
}).then(r => r.json());

// 2. Depositar $100 a Alice
const deposit = await fetch(`${BASE}/deposit`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
  body: JSON.stringify({ to_email: 'alice@tuapp.com', amount: 100, memo: 'Bienvenida' })
}).then(r => r.json());

// 3. Crear wallet para Bob y transferir
await fetch(`${BASE}/wallets`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
  body: JSON.stringify({ email: 'bob@tuapp.com', display_name: 'Bob' })
});

const transfer = await fetch(`${BASE}/transfer`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
  body: JSON.stringify({
    from_email: 'alice@tuapp.com',
    to_email: 'bob@tuapp.com',
    amount: 25,
    memo: 'Pago por servicio'
  })
}).then(r => r.json());

console.log(transfer.tx_hash); // 64 chars: a7f3c1e8d9...

Ejemplo completo — Python

Python

import requests

API_KEY = 'tk_live_xxxxx'
BASE = 'https://panel.tokiia.com/api/v1/waas'
headers = { 'Content-Type': 'application/json', 'X-API-Key': API_KEY }

# Crear wallet
requests.post(f'{BASE}/wallets', json={'email': 'alice@tuapp.com', 'display_name': 'Alice'}, headers=headers)

# Depositar
requests.post(f'{BASE}/deposit', json={'to_email': 'alice@tuapp.com', 'amount': 100}, headers=headers)

# Transferir
resp = requests.post(f'{BASE}/transfer', json={
    'from_email': 'alice@tuapp.com',
    'to_email': 'bob@tuapp.com',
    'amount': 25,
    'memo': 'Pago'
}, headers=headers)

print(resp.json()['tx_hash'])  # 64 chars hex

Account Numbersv1.1

Identificador legible único por merchant — opt-in, totalmente compatible con email

En la v1.1 agregamos un identificador alternativo para cada wallet: el account_number. Funciona como un número de cuenta (similar a un IBAN o CBU) y es único dentro de tu merchant.

Formato

Regex opcional^[A-Z]{2,6}\d{8}$Prefijo en mayúsculas (2 a 6 letras) + 8 dígitos. Ejemplo: OV00000001

Características

Opt-in. TOKIIA configura el account_prefix de tu merchant. Si no está configurado, las wallets siguen funcionando solo con email — todo sigue compatible con v1.0.
Auto-asignado. Al crear una wallet en un merchant CON prefijo, el sistema asigna automáticamente un account_number consecutivo y único.
Precedencia. En endpoints que aceptan email Y account_number en simultáneo, el account_number gana cuando vienen ambos.
Wallets viejas. Las wallets que existían antes de configurar el prefijo mantienen account_number = null. El backfill no es automático.
Aislamiento. Un merchant nunca puede consultar wallets de otro merchant aunque coincida el account_number — siempre filtramos por el merchant del API Key autenticado.

Compatibilidad con v1.0

Sin cambios para integraciones existentes. Si tu app hoy usa email en todos los endpoints, no necesitás cambiar nada — sigue funcionando igual. account_number es estrictamente opcional y aditivo.

Ejemplo

JSON

{
  "account_number": "OV00000042",
  "email": "alice@tuapp.com",
  "display_name": "Alice"
}

Nota: El prefijo (OV en el ejemplo) lo configura TOKIIA por merchant. Si necesitás activar account_numbers en tu cuenta, contactá a soporte@tokiia.com.

POST/waas/walletsAPI Key

Crea una wallet interna para un usuario. Cada email puede tener una sola wallet por merchant.

Parámetros del Body

email requeridostringEmail del usuario (único por merchant)

display_name opcionalstringNombre para mostrar del usuario

Ejemplo — cURL

cURL

curl -X POST "https://panel.tokiia.com/api/v1/waas/wallets" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "email": "alice@tuapp.com",
    "display_name": "Alice"
  }'

Ejemplo — JavaScript

JavaScript

const response = await fetch('https://panel.tokiia.com/api/v1/waas/wallets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'tk_live_xxx'
  },
  body: JSON.stringify({
    email: 'alice@tuapp.com',
    display_name: 'Alice'
  })
});

const wallet = await response.json();
console.log(wallet.id); // UUID de la wallet

Respuesta exitosa — 201v1.1

JSON

{
  "success": true,
  "data": {
    "id": "wal_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "alice@tuapp.com",
    "display_name": "Alice",
    "balance_usdt": 0,
    "account_number": "OV00000042",
    "bsc_address": "0x...",
    "is_active": true,
    "created_at": "2026-05-03T10:00:00Z"
  }
}

v1.1: La respuesta ahora incluye account_number. Será null si tu merchant aún no tiene account_prefix configurado. El request body no cambió — sigue aceptando solo email + display_name.

Nota: Si el email ya existe para tu merchant, retorna error 409 (wallet_exists).

GET/waas/walletsAPI Key

Lista todas las wallets de tu merchant con paginación.

Query Parameters

page opcionalnumberNúmero de página. Default: 1

per_page opcionalnumberResultados por página. Default: 25

Ejemplo — cURL

cURL

curl "https://panel.tokiia.com/api/v1/waas/wallets?page=1&per_page=25" \
  -H "X-API-Key: tk_live_xxx"

Ejemplo — JavaScript

JavaScript

const response = await fetch('https://panel.tokiia.com/api/v1/waas/wallets?page=1&per_page=25', {
  headers: { 'X-API-Key': 'tk_live_xxx' }
});

const data = await response.json();
console.log(data.wallets); // Array de wallets
console.log(data.total);   // Total de wallets

Respuesta — 200v1.1

JSON

{
  "wallets": [
    {
      "id": "wal_a1b2c3d4...",
      "email": "alice@tuapp.com",
      "display_name": "Alice",
      "balance_usdt": 75.00,
      "account_number": "OV00000042",
      "created_at": "2026-03-03T10:00:00Z"
    },
    {
      "id": "wal_e5f6g7h8...",
      "email": "bob@tuapp.com",
      "display_name": "Bob",
      "balance_usdt": 25.00,
      "account_number": "OV00000043",
      "created_at": "2026-03-03T10:01:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 25
}

v1.1: Cada wallet del array ahora incluye account_number. Las wallets viejas (creadas antes de configurar el prefijo) traen account_number: null.

POST/waas/depositAPI Key

Deposita fondos a una wallet. El depósito viene de SYSTEM — úsalo para cargar balance inicial o agregar fondos a tus usuarios.

Parámetros del Body

to_email opcionalstringEmail de la wallet destino. Requerido si no se manda to_account.

to_account opcionalstring(v1.1) Account number de la wallet destino. Alternativo a to_email — si vienen ambos, account gana.

to opcionalstring(v1.1) Alias aceptado para to_email.

amount requeridonumberMonto a depositar (mayor a 0)

memo opcionalstringNota o descripción del depósito

v1.1: Debe enviarse al menos uno de to_email, to_account o to. Si no, retorna 400 missing_recipient.

Ejemplo — cURL (email)

cURL

curl -X POST "https://panel.tokiia.com/api/v1/waas/deposit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "to_email": "alice@tuapp.com",
    "amount": 100,
    "memo": "Bienvenida"
  }'

Ejemplo — cURL (account_number)v1.1

cURL

curl -X POST "https://panel.tokiia.com/api/v1/waas/deposit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "to_account": "OV00000001",
    "amount": 100
  }'

Ejemplo — JavaScript

JavaScript

// v1.0 — por email
const response = await fetch('https://panel.tokiia.com/api/v1/waas/deposit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'tk_live_xxx'
  },
  body: JSON.stringify({
    to_email: 'alice@tuapp.com',
    amount: 100,
    memo: 'Bienvenida'
  })
});

// v1.1 — por account_number
const r2 = await fetch('https://panel.tokiia.com/api/v1/waas/deposit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'tk_live_xxx' },
  body: JSON.stringify({ to_account: 'OV00000001', amount: 100 })
});

const deposit = await response.json();
console.log(deposit.tx_hash); // Hash de 64 caracteres

Respuesta — 200v1.1

JSON

{
  "tx_hash": "a7f3c1e8d9b2e4f6a8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e0f2",
  "to": "alice@tuapp.com",
  "to_account": "OV00000001",
  "amount": 100,
  "status": "confirmed",
  "timestamp": "2026-05-03T10:02:00Z"
}

v1.1: La respuesta incluye to_account cuando la wallet destino tiene account_number asignado.

POST/waas/transferAPI Key

Transfiere fondos de una wallet a otra. Ambas wallets deben existir y el remitente debe tener saldo suficiente.

Parámetros del Body

from_email opcionalstringEmail de la wallet origen. Requerido si no se manda from_account.

to_email opcionalstringEmail de la wallet destino. Requerido si no se manda to_account.

from_account opcionalstring(v1.1) Account number de la wallet origen. Alternativo a from_email.

to_account opcionalstring(v1.1) Account number de la wallet destino. Alternativo a to_email.

from opcionalstring(v1.1) Alias aceptado para from_email.

to opcionalstring(v1.1) Alias aceptado para to_email.

amount requeridonumberMonto a transferir (mayor a 0)

memo opcionalstringNota o descripción de la transferencia

v1.1 — Reglas de identificación:

Si vienen email Y account para el mismo lado, account gana.
Si to_email no existe, la wallet destino se crea automáticamente.
Si to_account no existe, retorna 404 account_not_found (no se autocrea).

Ejemplo — cURL (email)

cURL

curl -X POST "https://panel.tokiia.com/api/v1/waas/transfer" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tk_live_xxx" \
  -d '{
    "from_email": "alice@tuapp.com",
    "to_email": "bob@tuapp.com",
    "amount": 25,
    "memo": "Pago por servicio"
  }'

Ejemplo — cURL (account_number)v1.1

cURL

curl -X POST "https://panel.tokiia.com/api/v1/waas/transfer" \
  -H "X-API-Key: tk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from_account": "OV00000001",
    "to_account": "OV00000002",
    "amount": 25
  }'

Ejemplo — JavaScript

JavaScript

// v1.0 — por email
const response = await fetch('https://panel.tokiia.com/api/v1/waas/transfer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'tk_live_xxx'
  },
  body: JSON.stringify({
    from_email: 'alice@tuapp.com',
    to_email: 'bob@tuapp.com',
    amount: 25,
    memo: 'Pago por servicio'
  })
});

// v1.1 — por account_number
const r2 = await fetch('https://panel.tokiia.com/api/v1/waas/transfer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'tk_live_xxx' },
  body: JSON.stringify({
    from_account: 'OV00000001',
    to_account: 'OV00000002',
    amount: 25
  })
});

const tx = await response.json();
console.log(tx.tx_hash); // a7f3c1e8d9... (64 chars)

Respuesta — 200v1.1

JSON

{
  "tx_hash": "b8e4d2a6f0c8e2a4d6b8f0a2c4e6d8b0a2c4e6f8d0a2b4c6e8f0a2b4c6d8e0",
  "from": "alice@tuapp.com",
  "to": "bob@tuapp.com",
  "from_account": "OV00000001",
  "to_account": "OV00000002",
  "amount": 25,
  "memo": "Pago por servicio",
  "status": "confirmed",
  "timestamp": "2026-05-03T10:05:00Z"
}

v1.1: La respuesta ahora incluye from_account y to_account cuando las wallets correspondientes tienen account_number asignado.

Errores comunes: saldo insuficiente (422), wallet no encontrada (404 wallet_not_found), account no encontrado (404 account_not_found), formato inválido (400 invalid_account_format), no puedes enviarte a ti mismo (400).

GET/waas/balanceAPI Key

Consulta el saldo de una wallet por email o por account_number.

Query Parameters

email opcionalstringEmail de la wallet a consultar. Requerido si no se manda account.

account opcionalstring(v1.1) Account number de la wallet. Alternativo a email — si vienen ambos, account gana.

v1.1: Si no se envía ni email ni account, retorna 400 missing_recipient.

Ejemplo — cURL (email)

cURL

curl "https://panel.tokiia.com/api/v1/waas/balance?email=alice@tuapp.com" \
  -H "X-API-Key: tk_live_xxx"

Ejemplo — cURL (account_number)v1.1

cURL

curl "https://panel.tokiia.com/api/v1/waas/balance?account=OV00000001" \
  -H "X-API-Key: tk_live_xxx"

Ejemplo — JavaScript

JavaScript

// v1.0 — por email
const response = await fetch('https://panel.tokiia.com/api/v1/waas/balance?email=alice@tuapp.com', {
  headers: { 'X-API-Key': 'tk_live_xxx' }
});

// v1.1 — por account_number
const r2 = await fetch('https://panel.tokiia.com/api/v1/waas/balance?account=OV00000001', {
  headers: { 'X-API-Key': 'tk_live_xxx' }
});

const data = await response.json();
console.log(data.balance_usdt); // 75.00

Respuesta — 200v1.1

JSON

{
  "email": "alice@tuapp.com",
  "account_number": "OV00000001",
  "balance_usdt": 75.00,
  "display_name": "Alice",
  "created_at": "2026-05-03T10:00:00Z"
}

GET/waas/transactionsAPI Key

Historial de transacciones del ledger. Puedes filtrar por usuario o ver todas las transacciones del merchant.

Query Parameters

email opcionalstringFiltrar por email de usuario

account opcionalstring(v1.1) Filtrar por account_number. Filtrado más eficiente que email — si vienen ambos, account gana.

page opcionalnumberNúmero de página. Default: 1

per_page opcionalnumberResultados por página. Default: 25

Ejemplo — cURL (email)

cURL

curl "https://panel.tokiia.com/api/v1/waas/transactions?email=alice@tuapp.com&page=1" \
  -H "X-API-Key: tk_live_xxx"

Ejemplo — cURL (account_number)v1.1

cURL

curl "https://panel.tokiia.com/api/v1/waas/transactions?account=OV00000001&page=1" \
  -H "X-API-Key: tk_live_xxx"

Ejemplo — JavaScript

JavaScript

// v1.0 — por email
const response = await fetch(
  'https://panel.tokiia.com/api/v1/waas/transactions?email=alice@tuapp.com&page=1',
  { headers: { 'X-API-Key': 'tk_live_xxx' } }
);

// v1.1 — por account_number
const r2 = await fetch(
  'https://panel.tokiia.com/api/v1/waas/transactions?account=OV00000001&page=1',
  { headers: { 'X-API-Key': 'tk_live_xxx' } }
);

const data = await response.json();
data.transactions.forEach(tx => {
  console.log(`${tx.tx_type}: ${tx.amount_usdt} — ${tx.tx_hash.slice(0, 16)}...`);
});

Respuesta — 200v1.1

JSON

{
  "transactions": [
    {
      "tx_hash": "b8e4d2a6f0c8e2a4d6b8f0a2c4e6d8b0a2c4e6f8d0a2b4c6e8f0a2b4c6d8e0",
      "prev_hash": "a7f3c1e8d9b2e4f6a8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e0f2",
      "from_email": "alice@tuapp.com",
      "to_email": "bob@tuapp.com",
      "from_account_number": "OV00000001",
      "to_account_number": "OV00000002",
      "amount_usdt": 25.00,
      "tx_type": "transfer",
      "memo": "Pago por servicio",
      "created_at": "2026-05-03T10:05:00Z"
    },
    {
      "tx_hash": "a7f3c1e8d9b2e4f6a8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c6d8e0f2",
      "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "from_email": "SYSTEM",
      "to_email": "alice@tuapp.com",
      "from_account_number": null,
      "to_account_number": "OV00000001",
      "amount_usdt": 100.00,
      "tx_type": "deposit",
      "memo": "Bienvenida",
      "created_at": "2026-05-03T10:02:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 25
}

v1.1: Cada transacción ahora incluye from_account_number y to_account_number cuando están disponibles. Para depósitos desde SYSTEM, from_account_number es null.

GET/waas/wallet/lookupAPI Keyv1.1

Resuelve una wallet por su account_number. Devuelve email, display_name y la dirección BSC para recibir pagos on-chain. Útil para confirmar al usuario cuando alguien tipea un account_number antes de transferir.

Query Parameters

account requeridostringEl account_number a buscar (ej: OV00000001)

Ejemplo — cURL

cURL

curl "https://panel.tokiia.com/api/v1/waas/wallet/lookup?account=OV00000001" \
  -H "X-API-Key: tk_live_xxx"

Ejemplo — JavaScript

JavaScript

const res = await fetch(
  'https://panel.tokiia.com/api/v1/waas/wallet/lookup?account=OV00000001',
  { headers: { 'X-API-Key': 'tk_live_xxx' } }
);
const json = await res.json();

if (!json.success) {
  if (json.code === 'account_not_found') {
    // Mostrar al usuario "Esa cuenta no existe"
  }
  throw new Error(json.error);
}

console.log(json.data.email);         // alice@tuapp.com
console.log(json.data.display_name);  // Alice

Respuesta — 200

JSON

{
  "success": true,
  "data": {
    "account_number": "OV00000042",
    "email": "alice@tuapp.com",
    "display_name": "Alice",
    "bsc_address": "0x...",
    "is_active": true
  }
}

Errores

HTTP	Código	Cuándo
400	`missing_recipient`	No se mandó el query param `account`
400	`invalid_account_format`	El account no matchea `^[A-Z]{2,6}\\d{8}$`
404	`account_not_found`	El account no existe en este merchant

Seguro de exponer: Solo devuelve wallets del merchant autenticado por la API Key. Es seguro llamar este endpoint desde cualquier integración del merchant.

GET/waas/verifyAPI Key

Verifica la integridad del hash chain. Puedes verificar una transacción específica o toda la cadena completa.

Query Parameters

tx_hash opcionalstringHash de la transacción a verificar. Si no se pasa, verifica toda la cadena

Ejemplo — cURL

cURL

# Verificar una transacción específica
curl "https://panel.tokiia.com/api/v1/waas/verify?tx_hash=b8e4d2a6f0c8..." \
  -H "X-API-Key: tk_live_xxx"

# Verificar toda la cadena
curl "https://panel.tokiia.com/api/v1/waas/verify" \
  -H "X-API-Key: tk_live_xxx"

Ejemplo — JavaScript

JavaScript

// Verificar transacción específica
const single = await fetch(
  'https://panel.tokiia.com/api/v1/waas/verify?tx_hash=b8e4d2a6f0c8...',
  { headers: { 'X-API-Key': 'tk_live_xxx' } }
).then(r => r.json());

// Verificar cadena completa
const chain = await fetch(
  'https://panel.tokiia.com/api/v1/waas/verify',
  { headers: { 'X-API-Key': 'tk_live_xxx' } }
).then(r => r.json());

console.log(chain.valid);              // true
console.log(chain.total_transactions); // 42

Respuesta — 200

JSON

{
  "valid": true,
  "total_transactions": 42,
  "checked": 42,
  "broken_at_sequence": null
}

Si la cadena está rota: valid: false y broken_at_sequence indica la posición exacta donde se rompió.

8 Capas de Seguridad

Cada transacción pasa por 8 capas de protección

Hash Chain SHA-256

Cada transacción incluye el hash de la transacción anterior, formando una cadena inmutable.

Firma HMAC-SHA256

Cada hash se firma con una clave secreta del servidor usando HMAC, impidiendo falsificación.

Nonce UUID v4

Cada transacción incluye un nonce único para prevenir ataques de replay.

TX Atómica SQL (ACID)

Descuento + acreditación + inserción en ledger ocurren en una sola transacción SQL. Todo o nada.

Backup Inmutable (Cloudflare R2)

Cada transacción se respalda como JSON en Cloudflare R2 con política write-once.

Row Level Security

Aislamiento por merchant a nivel de base de datos. Un merchant nunca puede ver datos de otro.

Rate Limiting

Límite configurable de transacciones por hora por merchant para prevenir abuso.

Verificación de Integridad

Cualquier usuario puede verificar la integridad de la cadena completa con GET /waas/verify.

Flujo de una Transferencia

Usuario A envía $25 a Usuario B
→ API valida auth + saldo + rate limit
→ Obtiene último hash de la cadena
→ Genera nuevo hash SHA-256 (incluye hash anterior)
→ Firma con HMAC-SHA256
→ TX atómica: descuenta A + acredita B + inserta ledger
→ Backup JSON en Cloudflare R2
→ Retorna tx_hash de 64 caracteres como recibo

SDKs & Ejemplos de Integración

Clases wrapper listas para copiar y pegar en tu proyecto

BeeChainClient — JavaScript

JavaScript

class BeeChainClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.base = 'https://panel.tokiia.com/api/v1/waas';
  }

  async request(method, path, body) {
    const res = await fetch(`${this.base}${path}`, {
      method,
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': this.apiKey,
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (!res.ok) throw new Error((await res.json()).error);
    return res.json();
  }

  createWallet(email, displayName) {
    return this.request('POST', '/wallets', { email, display_name: displayName });
  }

  deposit(toEmail, amount, memo) {
    return this.request('POST', '/deposit', { to_email: toEmail, amount, memo });
  }

  transfer(fromEmail, toEmail, amount, memo) {
    return this.request('POST', '/transfer', {
      from_email: fromEmail, to_email: toEmail, amount, memo
    });
  }

  balance(email) {
    return this.request('GET', `/balance?email=${email}`);
  }

  transactions(email, page = 1) {
    return this.request('GET', `/transactions?email=${email}&page=${page}`);
  }

  verify(txHash) {
    return this.request('GET', txHash ? `/verify?tx_hash=${txHash}` : '/verify');
  }
}

// Uso:
const bee = new BeeChainClient('tk_live_xxxxx');
await bee.createWallet('alice@miapp.com', 'Alice');
await bee.deposit('alice@miapp.com', 100);
const tx = await bee.transfer('alice@miapp.com', 'bob@miapp.com', 25, 'Pago');
console.log(tx.tx_hash);

BeeChainClient — Python

Python

import requests

class BeeChainClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base = 'https://panel.tokiia.com/api/v1/waas'
        self.headers = {
            'Content-Type': 'application/json',
            'X-API-Key': api_key
        }

    def create_wallet(self, email, display_name=None):
        return requests.post(f'{self.base}/wallets',
            json={'email': email, 'display_name': display_name},
            headers=self.headers).json()

    def deposit(self, to_email, amount, memo=None):
        return requests.post(f'{self.base}/deposit',
            json={'to_email': to_email, 'amount': amount, 'memo': memo},
            headers=self.headers).json()

    def transfer(self, from_email, to_email, amount, memo=None):
        return requests.post(f'{self.base}/transfer',
            json={'from_email': from_email, 'to_email': to_email, 'amount': amount, 'memo': memo},
            headers=self.headers).json()

    def balance(self, email):
        return requests.get(f'{self.base}/balance?email={email}',
            headers=self.headers).json()

    def transactions(self, email, page=1):
        return requests.get(f'{self.base}/transactions?email={email}&page={page}',
            headers=self.headers).json()

    def verify(self, tx_hash=None):
        url = f'{self.base}/verify'
        if tx_hash: url += f'?tx_hash={tx_hash}'
        return requests.get(url, headers=self.headers).json()

# Uso:
bee = BeeChainClient('tk_live_xxxxx')
bee.create_wallet('alice@miapp.com', 'Alice')
bee.deposit('alice@miapp.com', 100)
tx = bee.transfer('alice@miapp.com', 'bob@miapp.com', 25, 'Pago')
print(tx['tx_hash'])

Puedes copiar estas clases directamente en tu proyecto. También puedes pegar esta documentación a cualquier IA (Claude, ChatGPT, Gemini) y pedirle que integre BeeChain WaaS en tu aplicación.

Planes y Precios

Escala desde startup hasta enterprise

Plan	Precio/mes	Incluye	Para quién
Starter	$29	1,000 TX/mes, 1 API key, soporte email	Startups, proyectos pequeños
BusinessRecomendado	$99	10,000 TX/mes, 3 API keys, webhooks, soporte prioritario	Empresas medianas, e-commerce
Enterprise	$299	TX ilimitadas, API keys ilimitadas, SLA 99.9%, soporte dedicado	Plataformas grandes, MLM, fintech

¿Necesitas un plan personalizado? Contacta a nuestro equipo.

Contactar Ventas →

Un mercado de miles de millones

BeeChain compite en el espacio de Wallet as a Service junto a empresas valoradas en billones.

Empresa	Valuación / Funding	Qué ofrece
Fireblocks	$8 Billones	WaaS con MPC. $10T+ en TX aseguradas
Privy	Adquirido por Stripe	75M+ cuentas. Embedded wallets
Web3Auth	$13M Series A	20M+ usuarios activos/mes
Dfns	$16M Series A	Fidelity, Standard Chartered como clientes
TOKIIA (BeeChain)	Bootstrapped	Hash chain + HMAC. Integración en 5 min. Sin gas fees

BeeChain ofrece la misma funcionalidad core que estas empresas multimillonarias, con la ventaja de integración simple, sin gas fees, y precios accesibles desde $29/mes.

Errores WaaS

Códigos de error específicos de BeeChain WaaS

HTTP	Error	Descripción
400	`invalid_amount`	Monto debe ser mayor a 0
400	`self_transfer`	No puedes enviarte a ti mismo
400	`missing_email`	Email es requerido
400	`missing_recipient` v1.1	No se mandó ni email ni account_number
400	`invalid_account_format` v1.1	El account_number no matchea `^[A-Z]{2,6}\d{8}$`
401	`unauthorized`	API Key inválida o faltante
403	`waas_not_enabled`	Tu merchant no tiene WaaS activado
404	`wallet_not_found`	El email no tiene wallet en este merchant
404	`account_not_found` v1.1	El account_number no existe en este merchant
409	`wallet_exists`	Ya existe una wallet con ese email
409	`account_collision` v1.1	Conflicto al generar account_number (raro, reintentar)
422	`insufficient_balance`	Saldo insuficiente para la transferencia
429	`rate_limit_exceeded` v1.1	Se superó el límite del merchant
500	`internal_error`	Error del servidor

Formato de respuesta de error

JSON

{
  "success": false,
  "error": "El account_number no existe en este merchant",
  "code": "account_not_found"
}

Todas las respuestas de error usan este shape: success: false, error con el mensaje legible y code con un identificador estable ideal para pattern-matching desde el cliente. El campo code está presente en errores de business logic; en errores de autenticación (401) puede venir solo success + error.

TOKIIA Pay API v1 | BeeChain WaaS — tokiia.com — Dashboard

Acepta pagos crypto con TOKIIA Pay

Rápido

Seguro

Multi-chain

Autenticación

Base URL

Redes Soportadas

Guía Rápida

Regístrate como Merchant

Crea un Invoice

Muestra la Dirección

Recibe Confirmación

Verifica el Estado

Retira tus Fondos

Parámetros del Body

Ejemplo — cURL

Ejemplo — JavaScript

Respuesta exitosa — 201

Estados posibles

Ejemplo

Parámetros del Body

Ejemplo

Respuesta — 201

Ejemplo

Respuesta — 200

Query Parameters

Ejemplo

Ejemplo

Respuesta — 200

Ejemplo

Respuesta — 200

Webhooks

Eventos disponibles

Buenas prácticas

Rate Limits

Errores

¿Listo para integrar TOKIIA Pay?

Envía dinero de A a B con BeeChain WaaS

Instantáneo

Inmutable

Verificable

Comparativa

Casos de uso

Autenticación WaaS

Base URL

Ejemplo

Guía Rápida — 5 minutos

Obtén tu API Key

Crea una Wallet

Deposita Fondos

Transfiere entre Usuarios

Consulta Balances

Ejemplo completo — JavaScript

Ejemplo completo — Python

Account Numbersv1.1

Formato

Características

Compatibilidad con v1.0

Ejemplo

Parámetros del Body

Ejemplo — cURL

Ejemplo — JavaScript

Respuesta exitosa — 201v1.1

Query Parameters

Ejemplo — cURL

Ejemplo — JavaScript

Respuesta — 200v1.1

Parámetros del Body

Ejemplo — cURL (email)

Ejemplo — cURL (account_number)v1.1

Ejemplo — JavaScript

Respuesta — 200v1.1

Parámetros del Body

Ejemplo — cURL (email)

Ejemplo — cURL (account_number)v1.1

Ejemplo — JavaScript

Respuesta — 200v1.1

Query Parameters

Ejemplo — cURL (email)

Ejemplo — cURL (account_number)v1.1

Acepta pagos crypto
con TOKIIA Pay

Envía dinero de A a B
con BeeChain WaaS