Saltar al contenido principal

​
Descripción general

  • Ruta base: /api/v1
  • Autenticación: clave de API en encabezado x-api-key
  • Idempotencia: las operaciones de escritura requieren encabezado Idempotency-Key (formato UUID)
  • Formato de respuesta: todas las respuestas incluyen encabezado x-request-id para trazabilidad

​
Endpoints

  • GET /api/v1/wallets – Listar billeteras del usuario
  • GET /api/v1/wallets/balances – Saldos de la billetera del llamador (por cadena; predetermina a la billetera por defecto)
  • GET /api/v1/wallets/:address/balances – Saldos para una dirección de billetera propia específica
  • GET /api/v1/tx/:id – Obtener detalles de una transacción
  • POST /api/v1/send – Enviar activos nativos y tokens (EVM + Solana)
  • POST /api/v1/token/approve – Aprobación de tokens ERC20 (solo EVM)
  • POST /api/v1/contracts/send – Interacción genérica con contratos (solo EVM)
  • POST /api/v1/trade/quote – Obtener cotizaciones de intercambio (EVM + Solana)
  • POST /api/v1/trade/swap – Ejecutar intercambios (EVM + Solana)

​
Cadenas

Vea la lista completa en Cadenas soportadas. Use el slug chain (por ejemplo, base, solana-devnet).

​
Limitación de tasa

  • Escrituras (incluyendo POST /api/v1/trade/quote): 15 solicitudes por minuto por usuario
  • Lecturas: 60 solicitudes por minuto por usuario
  • Respuesta: HTTP 429 cuando se excede
  • Encabezados: Retry-After (segundos hasta la siguiente ventana)

​
Idempotencia (escrituras)

  • Todos los endpoints mutantes requieren Idempotency-Key.
  • Reutilizar una clave con el mismo cuerpo devuelve la respuesta 200 original.
  • Reutilizar una clave con un cuerpo distinto devuelve HTTP 409 con code: IDEMPOTENT_BODY_MISMATCH.
  • Reutilizar una clave sin una respuesta exitosa almacenada devuelve HTTP 409 con code: IDEMPOTENT_REPLAY.
  • Las claves están asociadas al usuario autenticado; se registra la ruta del endpoint.
  • Aplica a: POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap.

​
Manejo de errores

​
Formato de respuesta de error

{
  "error": "Mensaje de error legible",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
Códigos de error

  • UNAUTHORIZED – Autenticación faltante/inválida o clave de API (HTTP 401)
  • FORBIDDEN – Autenticado pero sin permiso para realizar la acción (HTTP 403)
  • NOT_FOUND – Recurso no encontrado (HTTP 404)
  • RATE_LIMITED – Límite de tasa excedido (HTTP 429)
  • INVALID_INPUT – Parámetros de solicitud inválidos (HTTP 400)
  • WALLET_NOT_FOUND – Billetera especificada no encontrada
  • USER_NOT_LINKED – Usuario no vinculado a Privy
  • WALLET_NOT_DELEGATED – Billetera no delegada al firmante del servidor
  • WALLET_ID_REQUIRED – Falta ID de billetera Privy
  • CHAIN_UNKNOWN – Cadena desconocida o no soportada
  • INSUFFICIENT_FUNDS – El remitente carece de fondos para valor/tarifa
  • IDEMPOTENT_BODY_MISMATCH – Cuerpo de solicitud diferente con la misma clave de idempotencia (HTTP 409)
  • IDEMPOTENT_REPLAY – Clave de idempotencia ya utilizada (HTTP 409)
  • PRIVY_RPC_ERROR – Error del servicio RPC de Privy
  • SEND_FAILED – Envío de transacción fallido
  • SERVICE_UNAVAILABLE – Servicio requerido no configurado
  • QUOTE_FAILED – Error del servicio de cotización (HTTP 400)
  • INTERNAL_ERROR – Error del servidor
Detalles de QUOTE_FAILED:
  • Solana/Jupiter: Algunos mints de Solana no son comerciables en Jupiter (lista permitida curada). En esos casos, esta API devuelve HTTP 400 con code: QUOTE_FAILED y un mensaje de error como: “Token not tradable on Jupiter”.
  • EVM/1inch: Si un token no es soportado por 1inch, la API devuelve HTTP 400 con code: QUOTE_FAILED y un mensaje como: “Token not tradable on 1inch”.
  • Esto es esperado cuando el token/mint de salida solicitado está marcado como no comerciable por el proveedor upstream, incluso si existen pools en otros lugares.

​
Validación

​
Formatos de dirección

  • EVM: debe coincidir con /^0x[a-fA-F0-9]{40}$/
  • Solana: debe ser una clave pública base58 válida

​
Parámetros comunes

  • Montos (EVM): Solo cadenas enteras (decimal o 0x-hex). Deben ser no negativos. Para ERC20 y value, deben caber en uint256.
  • Montos (Solana): Cadenas enteras en unidades base. Los montos SPL deben caber en rango sin signo de 64 bits.
  • Remitente (from): Opcional. Si se omite, se usa la billetera predeterminada del usuario para la cadena especificada.
  • Idempotencia: Todos los endpoints de escritura requieren encabezado Idempotency-Key. Las repeticiones con el mismo cuerpo devuelven la respuesta original.

​
Palabra clave de token nativo

Los endpoints de intercambio (/api/v1/trade/quote, /api/v1/trade/swap) aceptan la palabra clave NATIVE (sin distinción de mayúsculas/minúsculas) para fromToken/toToken:
  • EVM: NATIVE se resuelve a 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  • Solana: NATIVE se resuelve al mint de SOL envuelto So11111111111111111111111111111111111111112
  • Las respuestas devuelven direcciones resueltas (no NATIVE)
  • El endpoint de envío usa asset: "native" en lugar de direcciones de token para transferencias nativas

​
Convenciones

  • Selección de cadena: use el slug chain (p. ej., base, base-sepolia, solana-devnet).
  • Mapeo de sentinelas para Transaction.chainId en Solana: 0 = mainnet, -2 = testnet, -3 = devnet.
  • Idempotencia: única por usuario y clave; repeticiones devuelven la respuesta original; cuerpos distintos → 409.

​
Relacionado

Cadenas soportadas

Políticas y seguridad