x402 Stablecoin Payments
Some APIs and data providers are moving to per-request payments using USDC stablecoins instead of traditional API keys. The x402 protocol (developed by Coinbase and Cloudflare) standardizes this: a server responds with HTTP 402, the client signs a USDC payment, and retries with proof of payment. MeetLoyd agents handle this flow natively, enabling machine-to-machine micropayments governed by the same spending policies as your other payments.
This guide covers setup, agent tools, spending governance, and security considerations.
What is x402?
HTTP status code 402 (Payment Required) has existed since 1997 but was never standardized. The x402 protocol gives it a concrete implementation:
- A client requests a protected resource
- The server responds with 402 and a payment requirement (amount, token, recipient)
- The client signs a USDC payment and retries with a payment proof header
- The server verifies payment on-chain and serves the resource
This enables machine-to-machine micropayments — exactly the kind of interaction AI agents need when consuming paid APIs, data feeds, or premium services.
Why x402 on MeetLoyd?
| Benefit | Details |
|---|---|
| No API key provisioning | The agent pays per-request with USDC |
| Same governance | x402 spending is governed by the same AP2 spending policies as Stripe card payments |
| Full audit trail | Every on-chain payment is logged in the agent's activity stream |
| Enterprise-grade security | Wallet private keys are encrypted at rest using AES-256, stored in the same vault as LLM API keys |
x402 payments is an Enterprise-tier feature. Contact your account team to enable it.
Permissions
| Permission | Roles | Description |
|---|---|---|
x402:read | All roles | View wallet configuration, transaction history, feature status |
x402:write | Owner only | Configure, update, or delete the wallet (handles private keys) |
Wallet write operations are restricted to the Owner role because they involve sensitive cryptographic material.
Prerequisites
| Requirement | Details |
|---|---|
| MeetLoyd plan | Enterprise tier |
| EVM wallet | An Ethereum-compatible wallet on the Base network |
| USDC balance | USDC tokens on Base (mainnet or Sepolia testnet) |
| Spending policy | At least one AP2 spending policy configured (recommended) |
Setup
1. Configure a Wallet
Navigate to Settings > x402 Payments in the dashboard. You need to provide:
| Field | Description |
|---|---|
| Wallet address | Your EVM wallet address |
| Private key | Wallet private key (encrypted immediately on receipt) |
| Network | base (mainnet) or base-sepolia (testnet) |
The private key is encrypted server-side using AES-256 before storage. It is never logged, never returned in responses, and never leaves the vault in plaintext. Treat it with the same care as your LLM API keys.
2. Verify the Wallet
After configuration, verify the wallet is active and funded using the wallet check tool or the dashboard status indicator.
3. Configure Spending Limits
x402 payments follow your existing AP2 spending policies. If you have not configured spending limits yet, go to Security > Spending Policy to set per-transaction maximums, daily/weekly/monthly caps, and human approval thresholds.
Agent Tools
Three MCP tools are available to agents once x402 is enabled:
| Tool | Purpose |
|---|---|
| x402_check_wallet | Check configured wallet status and remaining spending limits |
| x402_pay | Pay for an x402-protected endpoint. Handles the full flow: fetches payment requirement, validates against spending policy, signs the transaction, retries with payment proof |
| x402_check_support | Probe a URL to determine whether it supports x402 payments, without making a payment |
x402_pay Parameters
| Parameter | Required | Description |
|---|---|---|
| url | Yes | The x402-protected endpoint URL |
| method | No | HTTP method (default: GET) |
| body | No | Request body for POST/PUT (JSON string) |
| merchantId | No | Merchant identifier for spending policy (default: URL hostname) |
| merchantCategory | No | Merchant category (e.g., api_service, data_provider) |
Spending Governance
x402 payments are subject to the same AP2 spending policies that govern Stripe card payments:
| Control | How It Applies |
|---|---|
| Per-transaction limit | Agent cannot pay more than the configured maximum per request |
| Daily cap | Total x402 spend across all agents is capped per day |
| Weekly/monthly cap | Rolling aggregate limits |
| Human approval threshold | Payments above the threshold create a HITL approval task |
| Audit logging | Every payment attempt (approved or denied) is logged |
If a payment exceeds any limit, the agent receives a clear explanation of which policy was violated. If human approval is required, the agent pauses and a task is created for the designated approver.
Start with conservative limits (e.g., $5 per transaction, $50 daily) and increase as you gain confidence in your agents' spending patterns.
Supported Networks
| Network | Chain ID | Use Case |
|---|---|---|
| Base Mainnet | 8453 | Production payments |
| Base Sepolia | 84532 | Testing and development |
Base was chosen for its low transaction fees and native USDC support via Coinbase. Additional networks may be supported in future releases.
Security
x402 wallet credentials receive the same security treatment as all secrets in MeetLoyd:
| Principle | Implementation |
|---|---|
| Encryption at rest | Private keys encrypted with AES-256, same vault infrastructure as LLM API keys |
| No plaintext exposure | Private keys never returned in responses, never logged, never included in agent context |
| Tenant isolation | Each tenant's wallet is scoped to their tenant boundary; no cross-tenant access |
| Fail closed | If the vault is unavailable, payment tools return an error rather than proceeding |
| Full audit trail | All wallet operations (configure, pay, check) are recorded in the activity stream and audit logs |
Next: Learn about Spending Policy to configure governance controls for all agent payments.