From an HTTP 402 response to on-chain USDC in a few lines of code — with TypeScript and Python SDKs, dynamic commissions, and subscription tiers.
AI agents need to pay for things: data APIs, compute, storage, and services provided by other agents. Traditional payment systems such as Stripe and PayPal are designed around human users. They require accounts, API keys, cards, approval flows, and sometimes KYC.
That model does not work particularly well for autonomous software.
x402 changes the interaction by turning HTTP 402 Payment Required into a crypto payment flow. An agent needs a wallet and a request. The server describes the payment requirements, the agent signs an authorization, and the payment is settled on-chain.
We built an open-source implementation with public TypeScript and Python SDKs. It runs on Base mainnet and supports Stripe-powered subscription tiers for customers who want lower platform commissions.
The problem: how does an agent pay for an API request?
Imagine an AI agent that needs real-time market data. It sends a request to an API, and the API charges $0.05 per request.
Traditional approaches create friction:
• Stripe: requires account setup, API keys, and a human-controlled payment flow.
• A crypto wallet: requires signing, gas management, and potentially an on-chain transaction for every small payment.
• x402: returns payment requirements in the HTTP response, allowing the agent to sign and retry the request automatically.
The result is a payment flow that fits naturally into the request-response model of the web.
Architecture
The high-level flow looks like this:
sequenceDiagram
participant A as AI agent
participant S as API server
participant F as Facilitator
participant B as Base mainnet
A->>S: GET /resource
S-->>A: 402 + payment requirements
A->>A: Sign EIP-3009 authorization off-chain
A->>S: GET /resource + X-PAYMENT
S->>F: Verify and settle payment
F->>B: Submit USDC transfer
B-->>F: Transaction confirmed
F-->>S: Payment settled
S-->>A: 200 + resource
Step by step:
1 The agent requests a paid resource.
2 The server responds with 402 Payment Required and includes the amount, network, recipient, and asset.
3 The agent SDK signs an EIP-3009 TransferWithAuthorization message off-chain.
4 The agent retries the request with an X-PAYMENT header.
5 The server forwards the authorization to a facilitator.
6 The facilitator verifies the signature and settles the transfer on-chain.
7 The server returns the resource with an HTTP 200 response.
The seller receives USDC. The facilitator pays the gas. The agent does not need to submit a separate gas-paying transaction for each request.
The Python SDK
The Python client handles payment discovery, signing, and retrying automatically:
from netthouse import X402Client
client = X402Client(private_key="0x...")
The SDK pays automatically when the API responds with HTTP 402.
result = client.fetch("https://api.netthouse.com/market-data")
if result.response.ok:
print(result.response.json()) # The paid resource
print("paid:", result.paid) # True
That is the basic integration. The SDK discovers the payment requirements, signs the authorization, retries the request, and returns the response.
The TypeScript SDK
The TypeScript API follows the same flow:
import { X402Client } from "@netthouse/sdk";
const client = new X402Client({ privateKey: "0x..." });
const result = await client.fetch(
"https://api.netthouse.com/market-data"
);
if (result.response.ok) {
console.log(await result.response.json());
console.log("paid:", result.paid);
}
The two SDKs expose the same concept and the same payment flow in different languages.
What is inside an EIP-3009 authorization?
The key part of the flow is the EIP-3009 TransferWithAuthorization signature. It is an off-chain authorization that a facilitator can submit on-chain later.
The signed message includes:
• from: the payer's wallet address.
• to: the seller's wallet address.
• value: the USDC amount, represented with USDC's six-decimal precision.
• validAfter and validBefore: the authorization's validity window.
• nonce: a unique value that prevents replaying the same authorization.
The SDK signs this data with the payer's private key. The facilitator verifies the signature and submits the transfer to Base. The seller receives USDC, while the facilitator covers the transaction gas.
The facilitator
The facilitator is the component responsible for turning the signed authorization into a settled payment. It:
8 Verifies the EIP-3009 signature.
9 Checks that the nonce has not already been used.
10 Submits the transaction to Base.
11 Pays the gas, which is reimbursed through the platform's commission model.
In our implementation, the facilitator runs as a Fastify module alongside the API. This keeps the deployment self-contained and avoids a dependency on a public facilitator service.
Resource discovery
An agent needs to know which resources are available and how much each one costs. We expose a /discover endpoint for this purpose.
A simplified response looks like this:
{
"x402Version": 1,
"items": [
{
"resource": "/market-data",
"type": "http",
"x402Version": 1,
"accepts": [
{
"scheme": "exact",
"network": "base",
"payTo": "0x9CeceD626E30b60AaFDe7DFa65b6B4BD4c674a64",
"maxAmountRequired": "50000",
"resource": "/market-data",
"description": "Crypto market snapshot",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}
]
}
]
}
The agent can call /discover, inspect the catalog, select a resource, and pay for it without requiring a separate account-management API.
Subscription tiers and dynamic commissions
Pay-per-request platforms often apply one flat commission to every customer. We added subscription tiers that reduce the platform commission for high-volume users.
Tier Price Platform commission
Free $0 10%
Pro $29/month 5%
Enterprise $299/month 2%
For example, when a Pro subscriber pays $0.05 USDC for a request, the platform commission is $0.0025. The remaining amount goes to the resource seller.
The commission is calculated at request time from the active subscription record.
How the subscription flow works
12 The user signs up through Clerk at app.netthouse.com.
13 The user selects a tier through Stripe Checkout.
14 A Stripe webhook updates the subscriptions table with the customer's tier and commissionPercent.
15 The x402 middleware reads the active tier for each request.
16 The payment is split automatically between the seller and the platform.
The dashboard is available in English and Russian.
Our first Base mainnet payment
We tested the complete flow on Base mainnet with a paid market-data request.
• Resource: /market-data
• Price: $0.05 USDC
• Network: Base mainnet
• Chain ID: 8453
• Transaction: 0xc177acae1afc9e6eee5bc1ab92c55d65e33b3b631ad8d83b03dfe3c5ddd659a
• Status: Successful
• Commission: 5% — Pro tier verified on-chain
We also performed an earlier testnet payment: 0xf9f758...2eb0e8.
The agent paid, the seller received USDC, the platform collected its commission, and the facilitator paid the gas. The complete flow worked end to end.
Suspending bad actors
Any payment system needs a way to stop abusive or compromised accounts. We built a suspension mechanism into the platform:
• Each organization has an is_suspended flag in the database.
• Suspended organizations receive HTTP 403 for payment requests.
• Suspended organizations are removed from /discover.
• A cron job named check-suspensions.ts runs hourly.
• Webhook events can trigger an automatic suspension.
This gives us a practical kill switch without requiring manual intervention for every case.
The technology stack
• Fastify: Node.js API server.
• viem and eth-account: EIP-712 and wallet-signing functionality.
• PostgreSQL on Neon: double-entry payment ledger.
• Stripe: subscriptions and billing.
• Clerk: authentication.
• Base mainnet: production network.
• Base Sepolia: testnet.
• Render: hosting with the api.netthouse.com custom domain.
• Cloudflare: DNS management.
Try it yourself
The project is open source and both SDKs are MIT licensed.
• TypeScript SDK: npm install @netthouse/sdk — source code
• Python SDK: pip install netthouse — source code
• Live API: api.netthouse.com/discover
• Dashboard: app.netthouse.com
• Main repository: github.com/netthouse/netthouse
Both SDKs are public, MIT licensed, and compatible with the Base mainnet deployment.
What's next?
We are working toward:
• Adding more resources to the catalog, including news, weather, and sentiment data.
• Releasing a Rust SDK for high-performance agents.
• Introducing the NETT utility token for discounts and governance.
• Building integrations with AI agent platforms such as LangChain, AutoGPT, and the MCP community.
Built with Fastify, viem, eth-account, and a lot of coffee.
Top comments (0)