Payments
Unwall provides three payment rails — x402 protocol, on-chain USDC transfer, and fiat ACH — all accessible through a single endpoint. ThePOST /v1/pay endpoint auto-routes to the correct rail based on the recipient field.
Unified Endpoint
recipient value and routes automatically:
| Recipient Format | Rail | Example |
|---|---|---|
URL (https://...) | x402 Protocol | "https://api.example.com/v1/data" |
Ethereum address (0x...) | USDC Transfer | "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18" |
| Object with bank details | Fiat ACH | {"name": "Acme Corp", "account_number": "...", ...} |
Three Payment Rails
x402 Protocol
Pay for API calls in USDC using the HTTP 402 payment standard. When the recipient is a URL:- Unwall proxies your request to the target API.
- If the API returns HTTP 402 with payment requirements, Unwall parses the payment details.
- Unwall signs a USDC authorization (EIP-3009) and retries the request with payment attached.
- The API response is returned to your agent.
Set
max_amount_usdc to cap how much your agent can spend per x402 call. See the x402 Protocol guide for details.USDC Transfer
Send USDC on-chain to any Ethereum address on Base. The transfer is executed through Bridge.xyz and recorded in the ledger.Fiat ACH
Convert USDC to USD and send via ACH bank transfer. Provide the recipient’s name, account number, routing number, and email. Bridge.xyz handles the off-ramp conversion and transfer.ACH transfers are not instant. Expect 2-3 business days for settlement.
Fee Model
Fees are tier-based and charged on top of the payment amount:| Plan | Fee Rate |
|---|---|
| Free | 2% |
| Pro | 1.5% |
| Business | 1% |
PLATFORM_FEE transaction in the ledger.
Idempotency
Include anidempotency_key in your request to prevent duplicate payments. If a request is retried with the same key, the original transaction is returned without creating a new one.
Transaction Lifecycle
Every payment goes through a defined set of statuses:| Status | Meaning |
|---|---|
pending | Payment recorded, not yet submitted to the payment provider |
processing | Submitted to Bridge.xyz or x402 facilitator, awaiting confirmation |
completed | Payment settled successfully |
failed | Payment failed. Balance is automatically credited back to the project. |
reversed | Payment was reversed after completion (e.g., ACH return) |
Safety Guarantees
Atomic balance debit
Atomic balance debit
Balance is debited using ledger RPC functions with PostgreSQL advisory locks for per-project serialization. Two concurrent payment requests cannot both succeed when only enough balance exists for one.
Fresh balance on every payment
Fresh balance on every payment
The project balance is never served from cache when authorizing a payment. It is always fetched directly from the ledger to prevent overdraw.
Automatic rollback on failure
Automatic rollback on failure
If a payment fails after the balance has been debited, the amount is automatically credited back to the project. If the rollback itself fails, the error is captured in Sentry for manual resolution.
x402 max amount cap
x402 max amount cap
For x402 payments, the
max_amount_usdc field ensures an agent never pays more than intended for a single API call.Deprecated Endpoints
The following endpoints still work butPOST /v1/pay is the recommended replacement:
| Deprecated Endpoint | Rail | Replacement |
|---|---|---|
POST /v1/payments | Fiat ACH | POST /v1/pay with bank details recipient |
POST /v1/x402/pay | x402 Protocol | POST /v1/pay with URL recipient |
POST /v1/usdc/transfer | USDC Transfer | POST /v1/pay with 0x address recipient |