[claude]

Requested by Kristof Gazso · Slack thread

Before: the docs have no page for Fast Bridge. The /v1/bridge API in the paymaster (the stack ending in pimlicolabs/paymaster#819) has no public reference, and the payments guides say Pimlico doesn't move funds between chains.

After: a new Fast Bridge section under References, with an overview, an endpoints reference and an errors reference, plus a how-to under Guides → Payments:

• docs/pages/references/fast-bridge/index.mdx: what it is, supported chains and tokens with the 1,000-token per-request cap, the eip3009 / permit2 / solana-transaction authorizations, recipient vs calls delivery, and the request lifecycle and statuses.
• docs/pages/references/fast-bridge/endpoints.mdx: POST /execute, POST /execute/sync (timeout, 1 to 300 s, default 30), GET /status/{requestId}, GET /addresses, every body field, and the bridge status object.
• docs/pages/references/fast-bridge/errors.mdx: rejection codes with their HTTP statuses and fixes, and the origin and destination leg error codes.
• docs/pages/guides/how-to/payments/bridge-usdc-with-fast-bridge.mdx and docs/snippets/payments/fast-bridge.ts: Base → Arbitrum USDC with a signed ReceiveWithAuthorization, then the calls and Permit2 (BSC) variants.
• Sidebars: fastBridgeSidebar in sidebars/references.ts, a Fast Bridge entry in the References sidebar and top nav in vocs.config.ts, and the how-to in paymentsSidebar.

How: everything is taken from the code on the paymaster bridge branches: src/fast-bridge/api/{routes,schema,errors,status,validate}.ts, fastBridgeConfigs.ts, bridge.ts and the legs. Nothing comes from a spec. The destination op is prepared while the origin is in flight (#819), which is described in "How a request runs". The prepare/send/cancel RPC methods #819 adds are left out: they're internal and gated like pimlico_sendUserOperationNow. /addresses uses the current field names on feat/fast-bridge-status (approvalAddress, multicaller). pnpm build passes, biome lint is clean on the changed TS files, and the snippet typechecks with tsc --strict.

Source: pimlicolabs/paymaster#819 (stacked on #818).

Open questions

• Release timing. The whole bridge stack (#818, #819, #821, #822) is still unmerged. #822 limits every /v1/bridge route to Pimlico's own API keys and adds a NOT_ENABLED (403) code, which isn't documented here. Should these docs wait for public access, or ship with a beta or allowlist note?
• /addresses field names. #819 still returns { spender, caller }, but feat/fast-bridge-status (b0dfffe) renamed them to { approvalAddress, multicaller }. The docs use the new names. Please confirm they're final.
• API host. I assumed https://api.pimlico.io/v1/bridge, since the paymaster service also serves /v2/account there. Please confirm.
• Refunds. A failed delivery leaves the request pending with funds in the Reserve. refunded exists in the type, but no refund flow is implemented yet (TODO in bridge.ts). The docs say that plainly. Is that what we want public, or do refunds land first?
• Fee. fee is hard-coded to 0 (TODO "per-user fee in bps"). The docs describe the field without naming a rate. With calls, clients encode amounts before they know amountOut, so a non-zero fee will need a quote endpoint or guidance.
• Solana origin. It needs the fee payer and the Reserve's token account, which only GET /addresses/solana in #821 returns. Should I add that endpoint once #821 merges? The Solana origin is described here, but no endpoint gives those addresses yet.
• Prod addresses. I left approvalAddress and multicaller out of the docs because they come from env (/addresses). Should we publish the production values?
• Leftovers on the multicaller. The docs warn that tokens your calls leave on multicaller aren't returned. Please confirm, and confirm whether calls[].value (native value) is usable, since the multicaller isn't funded with native tokens.
• Robinhood Chain naming (chain ID 4663, USDG) for the table.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 30, 2026 11:27pm UTC