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/payments/batch | Create up to 100 payment intents for the signed-in user; each returns its own signing data |
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/payments/batch constructs up to 100 payment intents in one call. It is not a live mass-payout service: every line still has to be signed by the payer's wallet and settled through a configured router, and production settlement is gated like any other payment intent.
- 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/refunds, /api/merchant/operations | Refund requests and the operator console — see Merchant Payments |
| — | /api/payouts/payroll/* | Contractor roster, self-service and pay runs — 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.