---
name: theopay-x402
description: Pay for and call any theopay.xyz x402-gated API endpoint from an AI agent. Handles the 402 → pay (USDC on Solana) → retry handshake automatically.
---

# theopay.xyz — x402 payment skill

Call paid HTTP endpoints listed on theopay.xyz. When an endpoint returns
`402 Payment Required`, sign a USDC payment on Solana and retry — the agent just
gets the `200 OK` response. No account, no API key, no checkout.

> Settlement is USDC on Solana. theopay takes a flat 1% margin; you pay the
> listed price. Endpoints live at `https://theopay.xyz/x/{slug}`.

## When to use

- You need data or compute behind a theopay gated URL (`https://theopay.xyz/x/{slug}`).
- A request to such a URL returns HTTP `402 Payment Required`.

## Setup

```
SOLANA_WALLET_KEY=   # base58 secret key for a funded Solana wallet (USDC + a little SOL for fees)
```

Install the client:

```
npm install x402-fetch
```

## Usage

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

const wallet = createSolanaWallet(process.env.SOLANA_WALLET_KEY!);

// Drop-in fetch that auto-resolves 402s: pays, then retries.
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

// GET example — fetch an X post
const res = await fetchWithPay(
  "https://theopay.xyz/x/fetch-x-post?id=1789012345678901234"
);
const post = await res.json(); // → { author: "@levelsio", text: "…", … }

// POST works too — method, headers, and body are forwarded to the origin
const res2 = await fetchWithPay("https://theopay.xyz/x/llm-rerank", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "…", docs: ["…"] }),
});
```

## The handshake (what happens under the hood)

1. `GET /x/{slug}` with no payment → `402 Payment Required`. The body + headers
   carry the requirements: `amount` (atomic units), `asset` (USDC), `network`
   (`solana`), and `payTo`.
2. Sign a USDC payment on Solana for `amount` to `payTo`.
3. Retry the request with the payment authorization header
   (`PAYMENT-SIGNATURE`, base64-encoded).
4. theopay verifies the payment on-chain (via its facilitator) and forwards your
   request to the seller's origin.
5. You get the origin's `200 OK` response. A `PAYMENT-RESPONSE` header carries
   the settlement details.

## Finding endpoints

Browse the marketplace at https://theopay.xyz/marketplace — every listing shows
its slug, price per call, and category.

## Notes & limits

- Settlement asset: **USDC on Solana**. Keep a small SOL balance for network fees.
- Prices are per call and set by the seller; theopay adds nothing on top (its 1%
  comes out of the seller's side).
- No account or API key is required — the signed payment is the authorization.
- Full protocol reference: https://theopay.xyz/docs and https://x402.gitbook.io/x402

> Status: the rail is implemented against the x402 spec. Confirm exact package
> versions and run a devnet test before high-volume mainnet use.