x402 Protocol (v2)

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 + payment-signature
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 (v2)

1ly uses x402 v2 for all paid API calls. This page documents the exact flow our APIs use so agents and developers can integrate with zero guesswork.

The Flow (exactly what happens)

1) Client calls the API
2) Server returns 402 + PAYMENT-REQUIRED header (and JSON body)
3) Client pays and retries with payment-signature
4) Server returns 200 + data + _1ly metadata

Step 1: Payment Challenge

Request:

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

Response (402):

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly8x...
 
{
  "x402Version": 2,
  "resource": {
    "url": "https://1ly.store/api/link/joe/weather",
    "description": "Weather API",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "10000",
      "payTo": "TREASURY_ADDRESS",
      "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
      "maxTimeoutSeconds": 300,
      "extra": { "feePayer": "FACILITATOR_ADDRESS" }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "payTo": "0xTREASURY",
      "asset": "0xUSDC_CONTRACT",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USDC", "version": "2", "decimals": 6 }
    }
  ],
  "error": "Payment required"
}

Notes:

PAYMENT-REQUIRED is a base64‑encoded JSON of the same object.
amount is in the smallest unit (USDC has 6 decimals → 10000 = 0.01 USDC).
network is CAIP‑2: solana:<cluster> or eip155:<chainId>.

Step 2: Payment + Retry

The client builds a payment signature using x402 and retries the same request with:

GET https://1ly.store/api/link/joe/weather
payment-signature: eyJ4NDAyVmVyc2lvbiI6Miwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoi...

payment-signature is a base64‑encoded payment payload produced by the x402 client.

Step 3: Access Granted

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "data": { "temperature": 72, "conditions": "sunny" },
  "_1ly": {
    "purchaseId": "abc123",
    "reviewToken": "xyz789"
  }
}

For Agent Developers

The easiest and recommended way is the 1ly MCP server. It handles x402 automatically:

ONELY_WALLET_SOLANA_KEY="/path/to/solana-wallet.json" npx @1ly/mcp-server

Then call any paid API:

1ly_call({ "endpoint": "joe/weather", "method": "GET" })

See the complete MCP Server docs for full setup and configuration.

Response Metadata (`_1ly`)

All paid API responses include _1ly with:

Field	Description
`purchaseId`	Unique purchase identifier
`reviewToken`	Token used to submit a review

Use these with 1ly_review or the reviews API.

Monetize Your API Telegram Gating