APIDirecciones de depósito
GET /v1/deposit-addresses
Direcciones de depósito de la empresa. Paginación por cursor.
| Dato | Valor |
|---|---|
| Método y ruta | GET /v1/deposit-addresses |
| Servidor | https://widget.fital.xyz |
operationId | listDepositAddresses |
| Acceso | Llave con el scope deposit_addresses:read |
| Firma de petición | No aplica |
| Idempotencia | No aplica |
Encabezados de la petición
| Encabezado | Obligatorio | Descripción |
|---|---|---|
Authorization | Sí | Bearer y tu llave. |
X-Fital-Scenario | No | Sólo simuladores: elige la respuesta que quieres practicar. |
Parámetros
| Parámetro | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
limit | consulta | texto | No | Filas por página, de 1 a 100. Por omisión, 25. |
cursor | consulta | texto | No | Valor de next_cursor de la página anterior. Hasta 1000 caracteres. |
Respuestas correctas
200 Correcto
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
data | lista de objeto | Sí | Filas de esta página. |
data[].address | texto o null | Sí | Dirección donde depositar. null mientras esté en processing. |
data[].chain | texto o null | Sí | Red de la dirección, en minúsculas. |
data[].created_at | texto o null | Sí | Fecha de creación. ISO 8601 en UTC. |
data[].currency | texto o null | Sí | Token que acepta, en mayúsculas. |
data[].id | texto | Sí | Identificador de la dirección, con prefijo dep_. |
data[].status | texto | Sí | Estado de la dirección. processing: El alta aún no se confirma y los demás campos llegan en null. active: Ya recibe depósitos. |
data[].warning | texto o null | Sí | Advertencia de uso. Muéstrala a quien vaya a depositar: dice también si en esa red un depósito rechazado no regresa automáticamente. |
has_more | booleano | Sí | true si hay más filas después de esta página. |
next_cursor | texto o null | Sí | Cursor de la página siguiente. null si no hay. |
Valores de data[].status
| Valor | Significado |
|---|---|
processing | El alta aún no se confirma y los demás campos llegan en null. |
active | Ya recibe depósitos. |
{
"data": [
{
"address": "0x0000000000000000000000000000000000000000",
"chain": "polygon",
"created_at": "2026-11-04T18:00:00.000Z",
"currency": "USDC",
"id": "dep_9vLsK3mNc7QxB1tZ5hYdR2fP",
"status": "active",
"warning": "Envía sólo USDC por la red polygon. Otro token u otra red puede no acreditarse."
}
],
"has_more": false,
"next_cursor": null
}Encabezados de la respuesta
| Encabezado | Contenido |
|---|---|
X-Request-Id | Identificador de la petición. Cítalo con soporte. |
Retry-After | Segundos a esperar, con 429 y a veces con 503. |
Errores
Todos usan la forma de Errores: error.code, message, request_id, details, retryable y docs_url. Decide por code.
| HTTP | Código | Cuándo sale | retryable |
|---|---|---|---|
| 400 | invalid_request | Algún parámetro o campo no cumple el esquema. Mira details.fields. | false |
| 401 | invalid_api_key | La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida. | false |
| 401 | wrong_environment | La llave es de otro ambiente. | false |
| 403 | forbidden_scope | La llave no tiene el scope de esta operación. details.required_scope lo nombra. | false |
| 403 | ip_not_allowed | La IP de origen no está activa en la lista de esa llave. | false |
| 403 | kyb_required | La empresa no tiene KYB aprobado o aún no está inscrita. | false |
| 403 | account_not_active | La cuenta no está activa. | false |
| 429 | rate_limited | Superaste un límite de peticiones. Llega con Retry-After. | true |
| 500 | internal_error | Fallo nuestro. El resultado de la petición no se conoce. | true |
| 503 | service_unavailable | El servicio no está disponible por ahora. El resultado de la petición no se conoce. | true |
Ejemplos de error
400 invalid_request:
{
"error": {
"code": "invalid_request",
"message": "Petición inválida",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {
"fields": {
"limit": "Entre 1 y 100"
}
},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
}
}401 invalid_api_key:
{
"error": {
"code": "invalid_api_key",
"message": "Credencial inválida",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key"
}
}403 forbidden_scope:
{
"error": {
"code": "forbidden_scope",
"message": "La llave no tiene permiso para esta operación",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {
"required_scope": "deposit_addresses:read"
},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope"
}
}429 rate_limited:
{
"error": {
"code": "rate_limited",
"message": "Demasiadas peticiones",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": true,
"docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited"
}
}500 internal_error:
{
"error": {
"code": "internal_error",
"message": "Error interno",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": true,
"docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error"
}
}503 service_unavailable:
{
"error": {
"code": "service_unavailable",
"message": "Servicio no disponible",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": true,
"docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable"
}
}Reintentos
Es una lectura: repetirla no tiene efecto.
429 rate_limited: Espera lo que indiqueRetry-Aftery repite.500 internal_error: Repite con espera exponencial.503 service_unavailable: Repite con espera exponencial. RespetaRetry-Aftersi viene.
Ver Reintentos y Límites.
Muestras
Variables de estas muestras: simulador público, sin cuenta
Define esto en tu terminal. Con estos valores las muestras corren tal cual contra el simulador público:
export FITAL_API="https://widget.fital.xyz/explorar/v1"
export FITAL_KEY="sk_test_sandbox_publica"En la cuenta de prueba o en producción cambia la base, la llave y el secreto, y sustituye los id de ejemplo por los tuyos. Ver Ambientes.
curl -sS "$FITAL_API/deposit-addresses" \
-H "Authorization: Bearer $FITAL_KEY"