> ## 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 routing between CCTP V2 and NEAR
Intents 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": "cctp_v2", "networkFee": "0.10", "estimatedOutAmount": "999.90", "etaSeconds": 30 },
  "ourFee": { "platformFee": "1.00", "gasFee": "0.05", "totalFee": "1.05" }
}
```

`quote.route` is `"cctp_v2"` or `"near_intents"` — read-only, informational;
`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
route-specific transfer (CCTP burn, or funding a NEAR Intents deposit
address). Returns immediately with a `pending` transfer — it does not wait
for completion.

```json theme={null}
// 201
{
  "bridgeTransfer": {
    "id": "br_9f21…",
    "route": "cctp_v2",
    "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`               | Waiting on CCTP attestation or the NEAR Intents solver   |
| `ready_to_mint`           | Attestation received, destination mint queued            |
| `completed`               | Funds delivered — `destTxHash` is set                    |
| `failed`                  | Did not complete — check `metadata` for the error        |
| `refunded`                | NEAR Intents returned funds instead of delivering (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            |