Bridge

Quote and execute cross-chain USDC/USDT transfers

All endpoints below are under https://api.puffinmoney.com/v1/gateway/api and require the X-API-Key header — see Authentication. See Bridging & swaps for how automatic routing works.

Quote a transfer

POST /bridge/quote

Field	Type	Required	Notes
walletId	string	✓	Source wallet — its chain/token are the transfer’s origin
toChain	string	✓	SOLANA, POLYGON, BSC, or BASE
toToken	string	✓	Destination token symbol
amount	string	✓	Decimal string, up to 8 dp
destinationAddress	string	✓	Recipient address on toChain

{
  "quote": { "route": "auto", "networkFee": "0.10", "estimatedOutAmount": "999.90", "etaSeconds": 30 },
  "ourFee": { "platformFee": "1.00", "gasFee": "0.05", "totalFee": "1.05" }
}

quote.route is an internal, opaque routing identifier — read-only, informational, not meant to be parsed or shown to your customers. POST /bridge picks the same route for the same inputs.

Execute a transfer

POST /bridge — same body as the quote request, plus optional Idempotency-Key header.

Reserves and debits the source wallet atomically, then kicks off the transfer on whichever route was quoted. Returns immediately with a pending transfer — it does not wait for completion.

// 201
{
  "bridgeTransfer": {
    "id": "br_9f21…",
    "route": "auto",
    "fromChain": "SOLANA",
    "toChain": "BASE",
    "amount": "1000.00",
    "destinationAddress": "0xabc...",
    "status": "attesting"
  }
}

Get transfer status

GET /bridge/:id

Status	Meaning
pending / source_sent	Debited, broadcasting the source-side transaction
attesting	Confirming the transfer before it can be delivered on the destination chain
ready_to_mint	Confirmed, destination delivery queued
completed	Funds delivered — destTxHash is set
failed	Did not complete — check metadata for the error
refunded	Funds were returned to you instead of delivered (rare)

Errors

Code	Meaning
bridge_not_configured	The selected route isn’t enabled for this corridor yet (503)
unsupported_asset	toChain/toToken isn’t in the WaaS matrix
insufficient_balance	Source wallet can’t cover amount + fees
not_found	walletId or transfer id doesn’t belong to you