Build on theopay.xyz

theopay.xyz is a hosted facilitator, proxy, and marketplace for x402 — the open standard for charging per HTTP request. Point us at your existing API and a price; we give you a gated proxy URL. When a buyer (human or agent) calls it, we issue an HTTP 402, verify their on-chain payment, and forward the request to your origin.

Call any gated endpoint with an x402-aware client. It intercepts the 402, signs the payment with your wallet, and retries — your code just sees a normal 200.

import { wrapFetchWithPayment } from "x402-fetch";
import { createSolanaWallet } from "x402-fetch/solana";

const wallet = createSolanaWallet(process.env.AGENT_SOLANA_KEY!);
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

const res = await fetchWithPay("https://theopay.xyz/x/fetch-x-post?id=1789…");
const data = await res.json(); // → { author: "@levelsio", text: "…", … }

1. 1.A client (human or agent) requests a gated endpoint with no payment.
2. 2.theopay.xyz responds 402 Payment Required + amount, asset, chain, and payTo.
3. 3.The client signs a USDC payment on Solana and re-sends with the X-PAYMENT header.
4. 4.theopay.xyz verifies the payment on-chain.
5. 5.We forward to your origin and stream back the response.

# 1) No payment → challenge
GET /x/fetch-x-post HTTP/1.1

HTTP/1.1 402 Payment Required
{
  "x402": {
    "amount": "2000",        // 0.002 USDC (6 decimals)
    "asset": "USDC",
    "chain": "solana",
    "payTo": "Theo…Treasury",
    "resource": "/x/fetch-x-post"
  }
}

# 2) With payment → success
GET /x/fetch-x-post HTTP/1.1
X-PAYMENT: <signed-solana-payment-authorization>

HTTP/1.1 200 OK
{ "author": "@levelsio", "text": "shipped a new feature 🚀", "likes": 4210 }

Listing

An API you've wrapped: an origin URL + a per-call price. Each listing gets a public slug and a gated proxy URL at /x/{slug}.

Gated proxy

The URL we host in front of your origin. It enforces payment, then forwards the request and streams back your origin's response.

Facilitator

The component that issues the 402 challenge and verifies the on-chain payment before releasing the response. theopay.xyz runs it for you.

Payment authorization

A signed Solana payment the client sends in the X-PAYMENT header. It both pays for and authorizes the request — no account needed.

Settlement

USDC moves on Solana per call to your treasury wallet, minus the flat 1% margin. Fast, cheap, deterministic finality.

Two audiences, two models. Buyers and agents have no account — calls are authorized by a signed Solana payment in the X-PAYMENT header. Sellers manage listings with a bearer API key.

curl https://theopay.xyz/api/v1/listings \
  -H "Authorization: Bearer tm_live_xxxxxxxxxxxx"

Every listing is reachable at a gated proxy path. Call it like the underlying API — we handle payment, then forward your request (method, headers, body) to the origin and stream back the response.

const res = await fetchWithPay("https://theopay.xyz/x/fetch-x-post");
// 402 → pay → retry happens automatically
const data = await res.json();

Programmatically manage the APIs you sell. All routes require a seller bearer token.

curl -X POST https://theopay.xyz/api/v1/listings \
  -H "Authorization: Bearer tm_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fetch X Post",
    "origin_url": "https://api.yoursite.com/v1/x-post",
    "price_usdc": 0.002,
    "category": "data"
  }'

# → { "id": "lst_123", "slug": "fetch-x-post",
#     "proxy_url": "https://theopay.xyz/x/fetch-x-post" }

Read the per-call payment record for your listings — for earnings, analytics, and reconciliation.

{
  "id": "txn_abc123",
  "listing_id": "lst_123",
  "amount_usdc": 0.002,
  "fee_usdc": 0.00002,
  "net_usdc": 0.00198,
  "chain": "solana",
  "signature": "5f…onchainSig",
  "status": "settled",
  "created_at": "2026-06-15T10:00:00Z"
}

theopay.xyz uses conventional HTTP status codes. The body is always JSON with an error object.

List endpoints are cursor-paginated. Pass limit (max 200) and the next_cursor from the previous response as cursor to fetch the next page. When next_cursoris null, you've reached the end.

GET /api/v1/transactions?limit=50

{
  "data": [ /* … */ ],
  "next_cursor": "txn_abc123",   // pass as ?cursor= for the next page
  "has_more": true
}

The management API is limited per API key. Paid proxy calls aren't rate-limited by us beyond your origin's own limits. Every response includes the headers below; on 429, back off and retry after Retry-After seconds.

Subscribe to transaction.settled to get a signed POST to your endpoint on every paid call — useful for ledgers, alerts, and provisioning. Verify the X-Theo-Signature header against your webhook secret.

POST https://your-app.com/webhooks/theomarket
X-Theo-Signature: t=1718446800,v1=5f2c…

{
  "event": "transaction.settled",
  "data": {
    "id": "txn_abc123",
    "listing_id": "lst_123",
    "net_usdc": 0.00198,
    "signature": "5f…onchainSig"
  }
}

Use a Solana devnet wallet and a devnet USDC mint to exercise the full 402 → pay → 200 loop without spending real funds. Point your client at the devnet RPC and fund the wallet from a faucet.

// point your client at Solana devnet
const wallet = createSolanaWallet(DEVNET_KEY, {
  rpcUrl: "https://api.devnet.solana.com",
});
// fund it: solana airdrop 1 <address> --url devnet
const res = await fetchWithPay("https://theopay.xyz/x/fetch-x-post");