x402 Protocol

The web's native payment layer. HTTP 402: Payment Required.

What is x402?

x402 is a protocol that enables machine-to-machine payments using HTTP's native 402 status code.

1. Agent: GET /api/data
2. Server: 402 Payment Required (here's how to pay)
3. Agent: GET /api/data + X-PAYMENT header
4. Server: 200 OK (here's your data)

Why x402?

No accounts — Pay with any crypto wallet
Instant — Sub-second payments
Programmable — AI agents can pay automatically
Micro-payments — Pay fractions of a cent

How 1ly Uses x402

When an agent calls your 1ly API link:

Step 1: Payment Challenge

GET https://1ly.store/api/link/joe/weather

Response:

HTTP/1.1 402 Payment Required
Content-Type: application/json
 
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "solana",
    "maxAmountRequired": "5000",
    "resource": "https://1ly.store/api/link/joe/weather",
    "payTo": "WALLET_ADDRESS",
    "extra": {
      "name": "Weather API",
      "feePayer": "FACILITATOR_ADDRESS"
    }
  }]
}

Step 2: Payment

The agent builds a transaction, signs it, and includes it in the header:

GET https://1ly.store/api/link/joe/weather
X-PAYMENT: eyJ0eXBlIjoiZXhhY3QiLCJuZXR3b3JrIjoi...

Step 3: Access Granted

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "data": {
    "temperature": 72,
    "conditions": "sunny"
  },
  "_1ly": {
    "purchaseId": "abc123",
    "reviewUrl": "https://1ly.store/api/reviews/abc123",
    "reviewToken": "xyz789"
  }
}

For Agent Developers

Using the x402 Client

import { createX402Client } from "@payai/x402-solana/client";
 
const client = createX402Client({ wallet: agentWallet });
const response = await client.fetch("https://1ly.store/api/link/joe/weather");
 
// Payment handled automatically!
console.log(response.data);

Manual Integration

See our Developer Docs for manual x402 transaction building.

Response Wrapper

All API responses include a _1ly metadata object:

Field	Description
`purchaseId`	Unique purchase identifier
`reviewUrl`	URL to submit a review
`reviewToken`	Token to authenticate the review

This enables agents to leave reviews, building reputation for your API.

Monetize Your API API Reference