# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.usexpay.xyz/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# What is xPay?

xPay lets you turn any existing HTTP endpoint into a paid microservice with no code changes. It wraps your API with a trust-minimized x402 paywall on Solana (USDC by default), gives you a shareable proxy URL, and auto-publishes your endpoint as an MCP tool discoverable by AI agents.

#### Why it matters

* Own your distribution with cryptographic, per-request payments
* Instant settlement to your wallet, near-zero fees, no custody risk
* AI-native: your endpoints become MCP tools agents can call directly
* No-code onboarding: point to an existing URL, set price/token, share the new link

#### What you can do

* Wrap any HTTP endpoint in a paid proxy: `https://api.usexpay.xyz/:username/:endpointName`
* Price per call in USDC or any SPL token (via mint address)
* List in a marketplace with ratings and examples
* Expose an MCP server for agents: `https://api.usexpay.xyz/mcp/:username`
* Use wallet-sign-in → JWT to manage your creator dashboard

See also:

* Creators Guide (how to register and monetize endpoints)
* API Reference (backend routes summary)
* MCP (how your endpoints become AI-native tools)


# How xPay works

From endpoint to revenue in minutes.

#### 1. Register your endpoint

* Provide: API URL, HTTP method, price, token (SPL mint), and wallet
* Optional: custom auth headers, sample request/response

#### 2. Get your xPay wrapper

* You receive `https://api.usexpay.xyz/:username/:endpointName`
* This URL enforces x402 payment automatically via Faremeter

#### 3. Start earning

* Share the proxy URL or list it in the xPay marketplace
* Each successful 2xx response increments earnings
* Your endpoints also become MCP tools for AI agents

**Notes**

* Protocol methods for MCP (listing, initialize) bypass payment; tool calls are paywalled
* Sample request/response helps generate MCP tool schemas and better marketplace docs


# Creator's Guide

Guide for API owners and maintainers

#### 1) Sign in and access your profile

* Use Coinbase CDP Wallet to sign a message
* Backend verifies signature and issues a JWT
* Update your username from the profile page (note: changes update proxy URLs)

#### 2) Register an endpoint

Provide:

* Name, description
* Original URL and HTTP method
* Price (`paymentAmount`) and token (`tokenType` = SPL mint address, e.g., USDC)
* Optional: custom auth headers for upstream, sample request/response

Result:

* You receive a paid proxy URL: `/:username/:endpointName`
* Use it anywhere you’d use your original URL

#### 3) List on the marketplace

* Public `GET /endpoints` displays listings with average rating and totals
* Share your listing URL and proxy URL with users and agents

#### 4) Earn and monitor

* Earnings increment on successful 2xx responses
* Dashboard shows calls, earnings, and reputation

#### Reviews and reputation

* Any authenticated user can rate an endpoint (1–5)
* Averages are computed and shown in the marketplace

Tips

* Provide sample requests/responses for better docs and MCP input schemas
* Use small, clear per-call prices to drive adoption


# Pricing & Tokens

#### Simple, per-call pricing

With xPay, you set a price for each request to your endpoint. Callers pay per use - no subscriptions, no manual billing. Payment is verified at request time using the x402 standard.

#### Default: USDC on Solana

* USDC is the default token for its stability and ubiquity.
* Prices are entered in standard units (e.g., `0.05` USDC per call).
* Funds settle instantly to your wallet, with near-zero fees.

#### Other SPL tokens

* You can choose any SPL token by providing its mint address.
* Keep prices simple and clear so users and agents can reason about cost.

#### Tips for setting prices

* Start low to encourage trial and adoption.
* Consider tiered endpoints (cheap “basic” calls, premium “heavy” calls).
* Communicate value: include examples and sample responses.

#### Refunds and failures

* x402 payment is verified before forwarding the request.
* If your upstream returns an error, callers still paid to pass the paywall. Keep your upstream reliable and communicate SLAs where relevant.


# Use Cases

#### Premium infrastructure (RPC, indexing, webhooks)

Wrap existing infra endpoints and charge per call in USDC. Share a stable paid URL with customers and agents; no keys or billing dashboards needed.

#### AI services (generation, retrieval, scoring)

Expose model calls as x402-protected endpoints. Agents can discover and call them via MCP, paying only for what they use.

#### Data APIs (market data, analytics, signals)

Monetize niche datasets with micro-pricing. Provide sample requests and responses so agents onboard themselves.

#### Automation hooks (jobs, triggers, micro-tasks)

Sell small automations or integrations as single-call tools. Great for the long tail of “tiny SaaS” tasks agents need frequently.

#### Community-maintained endpoints

Open-source teams can self-host a paid endpoint to cover costs. Payments settle directly to your wallet; no platform custody.

**Tips:**

* Start with a simple, low price to encourage trial
* Provide good examples and sample bodies
* List in the marketplace for agent discovery


# Why x402?

x402 is the native protocol for machine-to-machine payments. It brings a standard 402 Payment Required flow to HTTP, enabling per-request payments that are fast, composable, and easy for agents to use.

#### Benefits (from our landing narrative)

* Built for the agent economy: AI agents can pay per call without accounts or subscriptions
* No integration friction: replaces key juggling and billing backends with a single HTTP header
* Composable infrastructure: x402-wrapped endpoints become programmable building blocks
* Future-proof standard: a simple, widely adoptable payment rail for autonomous systems

#### How xPay uses x402

* Every paid proxy call passes through Faremeter x402 middleware
* Payments verify before forwarding the request; successful responses trigger earnings tracking
* Marketplace and MCP layers sit on top, enabling discovery and agent-native consumption

#### Learn more about x402

Read the [x402 official documentation](https://x402.org/)


# Concepts

### Concepts: x402, AI Agents, MCP

#### x402 in one minute

x402 brings “402 Payment Required” to modern APIs. Instead of subscriptions, dashboards, and key rotation, a caller attaches proof of payment to the request. If payment is valid, the request goes through; if not, the server returns 402. In xPay, this is enforced by Faremeter’s middleware on Solana, with USDC as the default token.

Why this matters:

* Per-request pricing that’s simple and transparent
* Works for humans and autonomous agents
* Payments settle instantly to your wallet

#### AI Agents

Agents are software that browse, plan, and call APIs on their own. They prefer protocols over custom dashboards, and they need pay-per-call rails. x402 is built for this world: agents can find your service, pay for a single call, and move on—no human sign-up or billing.

#### MCP (Model Context Protocol)

MCP is a standard that lets agents discover and call tools (like your endpoints) in a uniform way. xPay automatically exposes your endpoints as MCP tools, with friendly names, descriptions, and input shapes. Agents can list your tools, select one, pay via x402, and call it - all without bespoke integration work from you.


# MCP Servers

Each creator gets an MCP server at `https://api.usexpay.xyz/mcp/:username`. xPay turns your registered endpoints into MCP tools agents can call directly.

#### How it works

* On initialize, xPay creates (or resumes) a per-user MCP server session
* Tools are generated from endpoints; descriptions include method and cost
* Input schemas are derived from your `sampleBody` and `httpMethod`
* Payment is bypassed for protocol list/initialize methods, enforced for tool calls

#### Session management

* `POST /mcp/:username` with MCP payloads
* `GET /mcp/:username` and `DELETE /mcp/:username` for session operations
* Use `mcp-session-id` header to persist and reuse sessions

#### Best practices

* Provide realistic `sampleBody` and `sampleResponse`
* Keep names clear and descriptive for agent discovery
* Use fair, simple pricing to encourage agent adoption

#### Learn more about the MCP protocol

Read the [official MCP protocol documentation](https://modelcontextprotocol.io/)


# Glossary

**x402**\
An HTTP-friendly standard for per-request payments. Calls either include valid proof of payment or receive `402 Payment Required`.

**Faremeter**\
Middleware that enforces x402 on Solana. Verifies payment before a request is forwarded to your original API.

**MCP (Model Context Protocol)**\
A protocol that lets AI agents discover and call “tools” (functions/APIs) in a consistent way. xPay auto-publishes your endpoints as MCP tools.

**Agent**\
Software that plans, decides, and calls APIs autonomously using AI. Agents prefer protocols (like MCP and x402) over dashboards and keys.

**SPL Token**\
Token standard on Solana. USDC is an SPL token frequently used for stable pricing.

**Mint Address**\
The on-chain address identifying an SPL token. You can use any SPL token by its mint address.

**Proxy URL**\
The xPay-wrapped endpoint (e.g., `https://api.usexpay.xyz/:username/:endpointName`) that enforces x402 payments and forwards to your original API.

**Sample Body / Sample Response**\
Example request/response payloads you provide when registering an endpoint. Used to improve docs and auto-generate MCP tool schemas, as well as inform agents about the expected payload.


# FAQ

#### Do I need to change my API code?

No. Point xPay at your existing HTTP endpoint and set pricing. We handle x402 payment verification and proxying.

#### What tokens are supported?

Any SPL token by mint address. USDC on Solana is the default/recommended.

#### How do agents discover my tools?

Your endpoints become MCP tools under `/mcp/:username`. xPay also provides a marketplace listing.

#### When do I get paid?

Per-request, instantly, after payment verification. Funds settle directly to your wallet.

#### Can I control auth to my upstream API?

Yes. Provide optional custom auth headers that xPay will add when forwarding requests.

#### How are prices represented?

`paymentAmount` is a decimal in the token’s standard units (e.g., `0.05` USDC).

#### Is there a sandbox?

Use low `paymentAmount` and local backend. Prefer a dedicated Solana RPC (`SOLANA_RPC_URL`) during testing.