Credit-Based Access
For high-frequency or latency-sensitive interactions, agents should utilize Credit-Based endpoints.
Instead of signing and broadcasting a blockchain transaction for every single request, agents can pre-purchase "Credit Packs" and consume them instantly with a simple header.
The Protocol
Why use Credits?
- ⚡Zero Latency: No waiting for block confirmations. Responses are sub-millisecond.
- 📉Zero Gas Fees: Pay gas only once when topping up credits.
- 🤖Simpler Logic: No complex transaction signing loop for every call.
The Header
The only requirement is to identify the agent's wallet address.
Checking Balance
Agents should periodically check their credit balance to ensure uninterrupted service.
curl -X GET "https://api.x402layer.cc/api/credits/balance?endpoint=target-endpoint-slug" \
-H "x-wallet-address: 0xAgentAddress..."Example Response
{
"credits": 4500,
"endpoint": "target-endpoint-slug"
}Consuming Credits
To consume the endpoint, simply make the request with the wallet header. No 402 negotiation is required unless credits are insufficient.
async function callCreditEndpoint(url, agentWallet) {
const response = await fetch(url, {
method: 'POST', // or GET
headers: {
'Content-Type': 'application/json',
'x-wallet-address': agentWallet
},
body: JSON.stringify({ prompt: "Hello AI" })
});
if (response.status === 402) {
// Handle Insufficient Credits
// The body will contain the standard 402 payment challenge
const challenge = await response.json();
console.log("Need to top up!", challenge);
return;
}
const data = await response.json();
return data;
}Topping Up
When credits run low (or if a request returns 402), agents can purchase "Credit Packs". Currently, this is done via the Purchase URL returned in the 402 response or via the Dashboard UI.
🚧 Programmatic Top-Up
Direct programmatic top-up via the 402 protocol (sending a payment to "buy credits") matches the standard Pay-Per-Request flow.
Simply target the purchaseUrl endpoint with a Pay-Per-Request transaction to fund the balance.