Cotizar un prefondeo (tasa amarrada 30 minutos)

POST/prefondeosProbar

URL base

API key x-api-keyRecordar la clave en este navegador (localStorage, no sale de aquí)

Cabeceras

Idempotency-KeyGenerarÚnico por operación. El alcance es tu cuenta **y el modo** de la key: una `sk_test_` y una `sk_live_` no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera `Idempotent-Replayed: true`; con otro payload da `409 idempotency_key_reused`. Los campos secretos (el `url` de una gift card, una `apiKey` nueva, un `webhookSecret`) sólo llegan en la primera respuesta: al repetir llegan en `null`.

Cuerpo de la petición (JSON){ "montoUsdt": 1000000000 }

Enviar peticiónCopiar como curl

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

POST

/prefondeos

curl --request POST \
  --url http://localhost:3000/v1/prefondeos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "montoUsdt": 1000000000 }'

• Pruebas (sandbox)
• Producción

Scope prefondeos:write (no viene por defecto en ninguna key: pídelo). Exige Idempotency-Key. Manda uno de los dos montos: montoUsdt (micro-USDT a enviar) o montoBs (céntimos de Bs a recibir). La tasa es la del oráculo con tu spread; la comisión va dentro de la tasa y tus dispersiones con este saldo no pagan comisión por pago. Los Bs nunca se redondean hacia arriba. Manda los USDT a red/direccion del ticket, desde una de tus wallets de origen activas, y avisa con POST /prefondeos/{id}/envio antes de venceEn. Sin ninguna wallet de origen activa responde wallet_origen_requerida.

Sólo con tu key sk_live_. En tu cuenta de pruebas no se cotiza: tu prefondeo de pruebas ya viene cargado (GET /prefondeos).

Authorizations

• ApiKeyAuth

Parameters

Header Parameters

Idempotency-Key

string

Único por operación. El alcance es tu cuenta y el modo de la key: una sk_test_ y una sk_live_ no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera Idempotent-Replayed: true; con otro payload da 409 idempotency_key_reused. Los campos secretos (el url de una gift card, una apiKey nueva, un webhookSecret) sólo llegan en la primera respuesta: al repetir llegan en null.

Request Body^required

Media typeapplication/json

object

montoUsdt

Micro-USDT (1 USDT = 1000000)

integer

>= 1

montoBs

Céntimos de Bs

integer

>= 1

Examples

Exampleusdt

Mandar 1.000 USDT

{
  "montoUsdt": 1000000000
}

Responses

201

Ticket cotizado

Media typeapplication/json

Un ticket de prefondeo. Montos en minor units como texto: micro-USDT (6 decimales) y céntimos de Bs. Tasas en Bs por 1 USDT con 8 decimales.

object

id

string format: uuid

estado

cotizado → enviado (avisaste) → recibido (nuestro equipo lo vio en la red) → cargado (otra persona aprobó: tienes los Bs) → consumido (saldo en 0; vuelve a cargado si se revierte un pago). vencido si no avisaste a tiempo; rechazado si lo cancelaste o no llegó.

string

Allowed values: cotizado enviado recibido cargado consumido vencido rechazado

origen

pruebas: tu prefondeo de pruebas, ya cargado con Bs simulados (sin wallet)

string

Allowed values: cotizado manual excedente pruebas

red

Red donde se reciben los USDT

string

direccion

Wallet de recepción (la fija nuestro equipo). null en tu cuenta de pruebas o con una sk_test_

string

nullable

activo

string

Allowed values: USDT

usdtCotizado

string

bsCotizado

string

tasa

Tasa amarrada (con spread)

string

tasaMercado

string

nullable

spreadBps

integer

venceEn

string format: date-time

nullable

referencia

string

nullable

usdtEnviado

string

nullable

enviadoEn

string format: date-time

nullable

usdtRecibido

string

nullable

recibidoEn

string format: date-time

nullable

recibidoTarde

Llegó en la red después de venceEn; se cargó a la tasa de ese momento

boolean

tasaAplicada

La tasa con la que se cargaron los Bs

string

nullable

usdtCargado

string

nullable

bsCargado

string

nullable

usdtExcedente

USDT que llegaron de más (no se cargan en este ticket)

string

excedenteDestino

string

nullable

Allowed values: ticket_nuevo devuelto_fuera

saldoBs

Bs que le quedan al ticket

string

usdtConsumido

Costo en USDT de lo ya gastado

string

cargadoEn

string format: date-time

nullable

motivoRechazo

string

nullable

simulado

Cargado desde la cuenta de pruebas: no es dinero real

boolean

direccionOrigen

El from de la transferencia que anotó nuestro equipo (una de tus wallets de origen)

string

nullable

walletOrigenId

Tu wallet de origen registrada

string format: uuid

nullable

esperaWalletHasta

El USDT llegó desde una wallet sin registrar: el ticket espera hasta aquí (72 h, con su tasa) a que la registres y la aprobemos

string format: date-time

nullable

caducaEn

Sólo tu prefondeo de pruebas: a esta hora se cierra su saldo simulado (te llega prefondeo.vencido)

string format: date-time

nullable

creadoEn

string format: date-time

actualizadoEn

string format: date-time

Example

{
  "estado": "cotizado",
  "origen": "cotizado",
  "activo": "USDT",
  "excedenteDestino": "ticket_nuevo"
}

400

idempotency_key_required o validation_failed

Media typeapplication/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

409

tenant_entorno_no_permitido: con una key sk_test_, o en tu cuenta de pruebas (tu prefondeo de pruebas ya viene cargado)

Media typeapplication/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

422

tenant_sin_prefondeo_con_tasa, prefondeo_tope_superado (tickets abiertos o monto máximo por ticket) o wallet_origen_requerida (registra una wallet de origen y espera su aprobación)

Media typeapplication/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

503

prefondeo_sin_configurar

Media typeapplication/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}