Skip to main content

​
Overview

  • Base path: /api/v1
  • Authentication: API key via x-api-key header
  • Idempotency: write operations require Idempotency-Key header (UUID format)
  • Response format: all responses include x-request-id header for tracking

​
Endpoints

  • GET /api/v1/wallets – List user wallets
  • GET /api/v1/wallets/balances – Get balances for caller’s wallet (by chain; defaults to default wallet)
  • GET /api/v1/wallets/:address/balances – Get balances for a specific owned wallet
  • GET /api/v1/tx/:id – Get transaction details
  • POST /api/v1/send – Send native assets and tokens (EVM + Solana)
  • POST /api/v1/token/approve – ERC20 token approval (EVM only)
  • POST /api/v1/contracts/send – Generic contract interaction (EVM only)
  • POST /api/v1/trade/quote – Get swap quotes (EVM + Solana)
  • POST /api/v1/trade/swap – Execute swaps (EVM + Solana)

​
Chains

See the full list in Supported chains. Use the chain slug (for example, base, solana-devnet).

​
Rate limiting

  • Scope: Applied per API key to write endpoints and POST /api/v1/trade/quote
  • Limit: 10 requests per minute per API key
  • Response: HTTP 429 when exceeded
  • Headers: Retry-After (seconds until next window)

​
Idempotency (writes)

  • All mutating endpoints require Idempotency-Key.
  • Reusing a key with the exact same request body returns the original 200 response.
  • Reusing a key with a different body returns HTTP 409 with code: IDEMPOTENT_BODY_MISMATCH.
  • Reusing a key with no stored success response returns HTTP 409 with code: IDEMPOTENT_REPLAY.
  • Keys are scoped to the authenticated user; the endpoint path is recorded for traceability.
  • Applies to: POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap.

​
Error handling

​
Error response format

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
Error codes

  • UNAUTHORIZED, FORBIDDEN, NOT_FOUND, RATE_LIMITED, INVALID_INPUT, WALLET_NOT_FOUND, USER_NOT_LINKED, WALLET_NOT_DELEGATED, WALLET_ID_REQUIRED, CHAIN_UNKNOWN, INSUFFICIENT_FUNDS, IDEMPOTENT_BODY_MISMATCH, IDEMPOTENT_REPLAY, PRIVY_RPC_ERROR, SEND_FAILED, SERVICE_UNAVAILABLE, QUOTE_FAILED, INTERNAL_ERROR
QUOTE_FAILED specifics:
  • Solana/Jupiter: non-tradable mints return HTTP 400 with code: QUOTE_FAILED and a message like “Token not tradable on Jupiter”.
  • EVM/1inch: unsupported token returns HTTP 400 with code: QUOTE_FAILED and a message like “Token not tradable on 1inch”.
401 Unauthorized is returned when the x-api-key is missing or invalid.

​
Validation

​
Address formats

  • EVM: must match /^0x[a-fA-F0-9]{40}$/
  • Solana: must be a valid base58 public key

​
Common parameters

  • Amounts (EVM): integer strings only (decimal or 0x-hex). Must be non‑negative.
  • Amounts (Solana): integer strings in base units. SPL amounts must fit unsigned 64‑bit range.
  • Sender (from): optional. If omitted, the user’s default wallet for the specified chain is used.

​
Conventions

  • Chain selection: use the chain slug (for example, base, base-sepolia, solana-devnet).
  • Solana Transaction.chainId sentinel mapping: 0 = mainnet, -2 = testnet, -3 = devnet.
  • Idempotency: unique per user and key; repeats return the original response; mismatched bodies → 409.

Supported chains

Policies & Security

⌘I