Architecture
API routes
FurlPay exposes REST routes for payment preparation, agent integrations, authentication and read-only data. The route contract describes what a handler accepts; the rail registry describes whether a money-moving path is currently available.
Check rail status before execution
GET /api/rails before sending or relaying a payment. A route can return a quote, challenge or intent while settlement remains unavailable. If the status endpoint errors or reports an unknown status, do not infer that a rail is operational.Discovery and fee estimates
| Method | Path | Description |
|---|---|---|
| GET | /api/rails | Public registry of rails, networks, assets, limits and current operational status |
| GET | /api/payments/fees/estimate?amount=…&sourceChain=… | Public fee estimate; amount is in USD |
| GET | /openapi.json | Machine-readable API description |
The rail registry is the source for current payment availability. It may return 503 controls_unavailable when its operational status cannot be read. Treat that response as unknown, not as permission to proceed.
USDC payment intents
| Method | Path | Description |
|---|---|---|
| POST | /api/payments/create | Authenticated payment intent and EIP-712 signing data; can return 503 when production configuration is missing |
| POST | /api/payments/execute | Submit the user's signature to the configured payment flow |
| GET | /api/payments/[id] | Read the payment's current status |
| POST | /api/payments/refund | Request a refund where the payment and rail support it |
| POST | /api/payouts/batch | Create up to 100 independent USDC payment intents; production persistence is not configured and the route returns 503 |
The current merchant product supports fee quotes and non-custodial payment preparation. FurlPay-operated production settlement is listed separately and remains gated. The create route requires an authenticated user session and may require a step-up proof; an API key alone does not satisfy that requirement.
POST /api/payouts/batch is a development-stage intent-construction route, not a live mass-payout service. It accepts up to 100 Arbitrum USDC recipients as independent lines; the batch is not atomic, and production returns 503 until durable intent persistence is implemented. A created line still requires separate signing and settlement.
- A created payment ID is not a transaction hash.
202 Acceptedmay mean the payment is waiting for review or confirmation.- Only a confirmed terminal status with a transaction reference proves settlement.
- Use
Idempotency-Keyonly on routes that document support for it.
x402 and Machine Payments Protocol
| Method | Path | Description |
|---|---|---|
| GET | /api/x402/fx | Example paid resource; currently returns 503 while x402 operational controls are unavailable |
| POST | /api/x402/facilitator/verify | Validate an x402 payment payload |
| POST | /api/x402/facilitator/settle | Attempt x402 settlement when the production facilitator is configured |
| GET | /api/x402/settlement/[tx] | Check a pending x402 settlement |
| GET | /api/mpp/fx | Example paid resource using the MPP challenge and receipt headers |
The x402 endpoint returned 503 controls_unavailable with reason plan_limit on 11 October 2026. If it becomes available, challenge creation still does not mean x402 or MPP can settle a payment. Check each protocol's status in /api/rails and wait for a verified settlement result before releasing a paid resource.
Client-signed cross-chain routes
| Method | Path | Description |
|---|---|---|
| POST | /api/intents/cctp | Build a Circle CCTP burn or mint transaction |
| GET | /api/intents/cctp/attestation | Retrieve or poll a Circle Iris attestation |
| POST | /api/swaps/execute | Quote a LI.FI route and build transactions for client signing |
| GET | /api/transfers/gasless | Request the gasless USDC fee quote |
| POST | /api/transfers/gasless | Submit an EIP-3009 transfer for relaying when enabled |
CCTP and LI.FI transactions are non-custodial: the client reviews, signs and submits the transaction. A route quote can expire or become unavailable. Gasless transfers require a separate production fee-payer configuration. Confirm the relevant rail is available before showing an executable action.
Agent access and authentication
| Method | Path | Description |
|---|---|---|
| POST | /api/agents/keys | Register an agent public key; authenticated registrations can carry an owned spend policy |
| GET | /api/agents/keys | List the caller's agent keys when authenticated |
| DELETE | /api/agents/keys | Revoke an owned agent key |
| POST | /api/auth/webauthn | Register or authenticate a passkey |
| POST | /api/mcp | MCP transport; tools depend on the user's granted scopes |
The MCP transport and scoped agent controls do not bypass rail status or user authorization. Money-moving tools can prepare an action for approval; the available settlement path still depends on the selected rail.
Business, compliance and integration routes
These route groups have their own guides. Each guide states what the deployment must configure before the group does anything.
| Method | Path | Description |
|---|---|---|
| — | /api/merchant/payments, /api/checkout/merchant/[slug] | Payment links, invoices and hosted checkout — see Merchant Payments |
| — | /api/merchant/webhook | Merchant webhook endpoint — see Webhook Events |
| — | /api/merchant/payroll, /api/payouts/payroll/* | Contractor roster and pay runs — see Payroll & Payouts |
| — | /api/banking/virtual-accounts | Account requests only; nothing is issued without a provider — see Payroll & Payouts |
| — | /api/settlement/* | Workspace drafts and business onboarding — see Settlement Workspace |
| — | /api/compliance/* | Screening, cases, monitoring and reports — see Screening & Cases |
| — | /api/wallets/circle/* | Circle user-controlled wallets — see Circle |
| — | /api/onramp/*, /api/offramp/*, /api/ramp/orders | Third-party ramp providers — see Ramp Providers |
| — | /api/auth/telegram, /api/miniapp/* | Telegram sign-in and account view — see Telegram Mini App |
- Merchant Payments and Payroll & Payouts
- Settlement Workspace and Screening & Cases
- Circle, Ramp Providers and Telegram Mini App
- Configuration & Setup for credentials, flags, migrations and scheduled jobs
Routes that are not live products
Routes may exist for card issuing, local banking, off-ramp, travel booking and stock orders while the corresponding production product is unavailable. Do not integrate those paths based on a route name or generated example. See the service availability overview.
Request and response handling
- Use the authentication method documented for the specific route; there is no universal API-key shortcut.
- Validate all amounts, recipients, networks and transaction data on your side as well.
- Handle
400validation errors,401/403authorization failures,409conflicts,429rate limits, and503unavailable rails distinctly. - Verify signed webhook events using the integration-specific signing scheme before processing them; see Webhook Events.