Referencia de la API de retiros

Referencia completa de los endpoints de la API de retiros. Gestiona la configuración de retiros y crea solicitudes de retiro.

Valores de la estrategia de retiro

El campo strategy es un número tanto en la configuración como en las solicitudes de retiro:

Valor	Nombre	Descripción
1	multi-network	Transferencias directas por cadena; sin puente entre cadenas.
2	bridge	Usa Relay para el puente cuando la cotización lo requiere; si no, igual que multi-network.

Consulta Estrategia de retiro para más detalles. Para ver cómo se paga el gas (paymaster, autofinanciación, hot wallet), consulta Financiación del gas y las comisiones.

Tipos de cadena válidos

Las direcciones de retiro se indexan por tipo de cadena. Las claves válidas son: evm, solana, bitcoin, tron, cosmos, polkadot, move, ton. Úsalas como claves en:

• Configuración de retiros: addresses, por ejemplo { "evm": "0x...", "solana": "...", "bitcoin": "bc1q..." }
• Payment Intents y enlaces de pago: withdrawal_addresses, con la misma forma

Cada dirección se valida para su tipo de cadena (EVM, Solana, Bitcoin, etc.). Para listar redes por tipo de cadena, usa GET /payments/networks?chainType=evm (u otro tipo de cadena válido). Consulta Mínimos de pago para los mínimos por tipo de cadena.

Direcciones de retiro por pago (por tipo de cadena)

Al crear un Payment Intent o un enlace de pago, puedes definir opcionalmente withdrawal_addresses (o withdrawalAddresses en los enlaces) como objeto clave-valor. Las claves son tipos de cadena de la tabla de redes (por ejemplo evm, solana, bitcoin). Cada valor es la dirección de retiro de esa cadena. Si se omite o está vacío para una cadena, se usa el valor por defecto de tu cuenta en la configuración de retiros para ese tipo de cadena. Las direcciones se validan por cadena (EVM, Solana, Bitcoin, etc.).

URL base

https://api.orcarail.com/api/v1

Configuración de retiros

Obtener la configuración de retiros

Obtén la configuración de retiros del usuario autenticado (direcciones por tipo de cadena y estrategia). isEnabled es siempre true: los retiros son automáticos.

GET /withdrawals/settings

Autenticación

• Token Bearer (JWT): obligatorio

Respuesta

{
  "id": "uuid",
  "userId": "uuid",
  "addresses": {
    "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "solana": "GTtzwxqy67xx9DVESJjx28TgXqpc8xTqtiytgNMaQBTE",
    "bitcoin": "bc1q..."
  },
  "isEnabled": true,
  "strategy": 1,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Las claves de addresses son tipos de cadena (evm, solana, bitcoin, tron, cosmos, polkadot, move, ton). Cada dirección se valida para esa cadena. Devuelve null si aún no hay configuración.

Actualizar la configuración de retiros

Crea o actualiza la configuración de retiros.

PUT /withdrawals/settings

Autenticación

• Token Bearer (JWT): obligatorio

Cuerpo de la petición

Todos los campos son opcionales. Incluye solo los campos que quieras actualizar.

Parámetro	Tipo	Obligatorio	Descripción
addresses	object	No	Direcciones de retiro por tipo de cadena. Claves: evm, solana, bitcoin, etc. Valores: dirección de esa cadena. Se validan contra una red de ese tipo de cadena.
strategy	number	No	Estrategia de retiro (por ejemplo multi-network, bridge)

Respuesta

La misma forma que en GET; addresses es el objeto clave-valor. Se requiere al menos una dirección. Las direcciones se validan contra redes del mismo modo que la organización: una organización sandbox acepta direcciones de testnet (por ejemplo Bitcoin tb1…) y una organización live, de mainnet. Guardar la configuración activa los retiros automáticos; no hay retiro manual.

Solicitudes de retiro

Listar solicitudes de retiro

Lista las solicitudes de retiro del usuario autenticado.

GET /withdrawals/requests

Autenticación

• Token Bearer (JWT): obligatorio

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
limit	number	No	Número máximo de solicitudes que se devuelven

Respuesta

[
  {
    "id": "uuid",
    "userId": "uuid",
    "amount": "0.1",
    "tokenId": "uuid",
    "sourceNetworkId": "uuid",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "strategy": 1,
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Resumen de retiros

Obtener el resumen de retiros

Obtén un resumen de saldos y totales de retiro por red y token.

GET /withdrawals/summary

Autenticación

• Token Bearer (JWT): obligatorio

Respuesta

{
  "byNetwork": [
    {
      "networkId": 1,
      "networkName": "Ethereum",
      "totalAmount": "100.50",
      "totalUsdcValue": "100.50"
    }
  ],
  "byToken": [
    {
      "tokenId": 1,
      "tokenSymbol": "USDC",
      "totalAmount": "100.50",
      "totalUsdcValue": "100.50"
    }
  ],
  "totals": {
    "totalEarnedUsdc": "1250.50",
    "totalWithdrawnUsdc": "500.0",
    "remainingUsdc": "750.5"
  }
}

Códigos de estado

Código de estado	Descripción
200	Correcto
201	Creado
400	Petición incorrecta
401	No autorizado
404	No encontrado
500	Error interno del servidor

Consulta también

• Estrategia de retiro: multired frente a puente y dónde definir la estrategia
• Financiación del gas y las comisiones: paymaster, autofinanciación nativa y hot wallet
• Panel: resumen del panel con los saldos
• Pagos: enlaces de pago y transacciones