Overview#
Onchain OS Payment offers two payment methods: One-Time Payment and Batch Payment.
- One-Time Payment: One request, one settlement, each transaction submitted on-chain individually. Suitable for high-value scenarios that require immediate on-chain confirmation.
- Batch Payment: Confirmed immediately upon request; on-chain settlement is completed in batches in the background. Suitable for high-frequency, low-value continuous calls by AI Agents.
Both methods support the X Layer network, accept USDG and USDT, with zero Gas fees.
How It Works#
Both payment methods share the same x402 protocol framework and API interface. The difference lies in the signature method and settlement timing.
One-Time Payment#
Each request independently completes a full payment:
- The Buyer's payment signature is an EOA signature (converted via signConvert), which can be directly accepted by on-chain contracts
- After the Seller calls
/settle, the Facilitator submits the transaction on-chain - Supports both synchronous settlement (returns after on-chain confirmation) and asynchronous settlement (returns immediately after submission)
→ For detailed integration guide, see One-Time Payment
Batch Payment#
The Seller receives confirmation immediately after the Buyer signs; on-chain settlement is completed asynchronously in batches in the background:
- The Buyer signs directly with a session key (skipping signConvert); the signature cannot be directly accepted by on-chain contracts
- After the Seller calls
/settle, the Facilitator stores the signature in the database and immediately returnsstatus: "success" - In the background, the TEE (Trusted Execution Environment) compresses multiple signatures into a single on-chain transaction, significantly reducing Gas costs
- Security guarantee: session key signatures are settled collectively by the TEE; Sellers cannot bypass the Facilitator to submit on-chain independently
→ For detailed integration guide, see Batch Payment
Use Cases#
Choose the appropriate method based on your business scenario:
| Your Scenario | Recommended Method |
|---|---|
| Each call has a clear price; delivery is irrevocable once completed (e.g., report generation, file download) | One-Time Payment |
| Resources should only be delivered after receiving on-chain confirmation | One-Time Payment |
| API is called at high frequency by AI Agents continuously, with very small per-call amounts (e.g., tool-chain orchestration, streaming billing) | Batch Payment |
| Latency-sensitive; millisecond-level response takes priority over immediate settlement confirmation | Batch Payment |
If your business covers multiple scenarios above, you do not need to choose one over the other. Return both the exact and aggr_deferred schemes in the 402 response, and the system will automatically match based on the Buyer's capabilities.