REST API Reference — Vellum Cash GitBook

[ WARNING ]

The Vellum API is in beta. Endpoints, response shapes, and rate limits may change without notice while the protocol is in active development. Do not build production systems against it yet — pin your integration to a specific deployment and subscribe to status updates.

§Base URL & Conventions#

All endpoints are served by our API:

bash

https://api.vellum.cash

All requests and responses are JSON (Content-Type: application/json).

CORS is enabled for browser integrations.

Successful responses return { "success": true, "data": ... }; errors return { "success": false, "error": "message" } with an appropriate HTTP status code.

§POST /quote#

Returns a real-time bridge quote with fee breakdown for a route. Prices are sourced live from Binance.

Request body:

Field	Type	Description
`sourceChain`	string	One of: Ethereum Mainnet, Base, Optimism, Robinhood Chain, Solana, Arc Blockchain
`destChain`	string	Destination chain (same enum)
`sourceToken`	string	`ETH`	`SOL`	`USDC`
`amount`	number	string	Amount to bridge in source token units
`privacyTier`?	string	`STANDARD SHIELD`	`PARANOID DELAY`	`TRANCHE SHRED`

Response (truncated):

json

{
  "success": true,
  "data": {
    "quoteId": "quote_m4xk2_9f3a1",
    "sendUsd": 5000.00,
    "protocolFeePercent": 0.35,
    "totalFeeUsd": 18.62,
    "receiveAmount": 4981.38,
    "receiveAmountFormatted": "4981.38",
    "estimatedTime": "Instant ZK relay · ~1.5 min",
    "expiresAt": 1790000000000
  }
}

§POST /bridge#

Creates a conduit order: computes the quote, enforces min/max limits ($50 – $25,000), and generates a single-use ephemeral deposit address with an exported private key.

Request body: same fields as /quote, plus a required recipient (destination address — 0x-prefixed for EVM destinations, base58 for Solana).

Response (truncated):

json

{
  "success": true,
  "data": {
    "orderId": "cnd_m4xk2_a1b2c3d4",
    "nonce": "0x9a12...e44f",
    "depositAddress": "0x7A93f81eC9042b781Bde3a8930Fce9812A49B801",
    "depositPrivateKey": "0x...",
    "status": "WAITING_FOR_DEPOSIT",
    "expiresAt": 1790000000000
  }
}

[ IMPORTANT ]

depositPrivateKey is returned once at creation. The depositor keeps full custody of the ephemeral wallet — store it if recovery may be needed.

Order statuses: WAITING_FOR_DEPOSIT → DEPOSIT_DETECTED → ZK_PROVING → RELAYER_DISPATCH → COMPLETED.

§GET /bridge/:id#

Looks up an order by order ID (cnd_…), nonce, or deposit address. Partial matches are supported.

Response: { "success": true, "data": <BridgeOrder> } or 404 if not found.

§GET /bridge/:id/deposit-status#

On-chain deposit monitor for an order's ephemeral address. Scans the source chain via public RPCs (native token balance or USDC balanceOf; SPL token accounts on Solana) and transitions the order to DEPOSIT_DETECTED once sufficient funds arrive.

Response:

json

{
  "success": true,
  "data": {
    "orderId": "cnd_m4xk2_a1b2c3d4",
    "status": "WAITING_FOR_DEPOSIT",
    "detected": false,
    "receivedAmount": 0,
    "expiresAt": 1790000000000,
    "expired": false,
    "scannedAt": 1789999800000
  }
}

§GET /prices#

Current ETH / SOL / USDC prices used for quotes.

Response: { "success": true, "data": { "ETH": ..., "SOL": ..., "USDC": 1, "lastUpdated": ..., "source": "binance" } }