> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puffinmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api/authentication).
See [Bridging & swaps](/bridging) 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`                            |

```json theme={null}
{
  "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.

```json theme={null}
// 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            |