> ## Documentation Index
> Fetch the complete documentation index at: https://docs.indexy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Payments

> How the x402 payment protocol works with the Indexy API

## What is x402?

[x402](https://x402.org) is an HTTP-native payment protocol. Certain Indexy API endpoints require a small USDC payment on Base. When a request is made without a valid payment, the server responds with `HTTP 402 Payment Required`. A compatible client intercepts this response, signs and submits an on-chain payment, and retries the request automatically.

## Affected endpoints

| Action                | Endpoint                     | Cost                | Notes                                                            |
| --------------------- | ---------------------------- | ------------------- | ---------------------------------------------------------------- |
| Create an index       | `POST /beta/indexes/agent`   | 1.00 USDC           | First 3 indices per agent are free; charged from the 4th onwards |
| Get index information | `GET /beta/indexes/:indexId` | 0.01 USDC           | Free for the index owner; charged for any other caller           |
| List indexes          | `GET /beta/indexes/agent`    | 0.01 USDC per index | Charged based on the number of indexes returned                  |

## Using the MCP (no action needed)

If you are running the [Indexy MCP Server](https://github.com/indexy-xyz/mcp/blob/main/README.md) with a Web3 wallet (`OWNER_WALLET_PRIVATE_KEY` or `OWNER_WALLET_KEYSTORE_PATH`), **payments are handled automatically**. The MCP wraps every API call with an x402-compatible fetch client and signs payments transparently using your wallet. As long as your wallet holds USDC on Base, no additional setup is required.

<Info>
  API Key (`INDEXY_API_KEY`) mode does not support x402 payments. Use Web3 wallet authentication to enable automatic payments via the MCP.
</Info>

## Calling the API directly

If you are building a custom client that calls Indexy endpoints directly (outside of the MCP), you need to handle 402 responses yourself using the `@x402/fetch` package.

### Setup

```bash theme={null}
npm install @x402/evm @x402/fetch viem
```

### Example (Node.js / TypeScript)

```ts theme={null}
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");

const paidFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [
    {
      network: "eip155:8453", // Base mainnet
      client: new ExactEvmScheme(account),
    },
  ],
});

// Use paidFetch exactly like fetch — 402s are handled automatically
const res = await paidFetch("https://indexy.co/beta/indexes/agent", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({ name: "My Index", selectedAssets: [...] }),
});
```

Your wallet must hold **USDC on Base mainnet** (chain ID `8453`). You can acquire it via [Coinbase](https://www.coinbase.com), [Bridge](https://bridge.xyz), or any Base-compatible DEX.

## Payment flow

```
Client                              Server
  |                                    |
  |-- POST /beta/indexes/agent ------> |
  |                                    |
  |<-- 402 Payment Required ---------- |
  |    X-Payment-Requirements: ...     |
  |                                    |
  | [x402 client signs & submits tx]   |
  |                                    |
  |-- POST /beta/indexes/agent ------> |
  |   X-Payment: <proof>               |
  |                                    |
  |<-- 200 OK + index data ----------- |
```

## Payment protection & free retries

If you have paid for a request and it fails due to a server error, **you will not be charged again** for that specific call. The payment proof is tied to the original request, and the server allows you to retry it at no additional cost until it succeeds.

This means:

* A successful payment is never lost due to a transient error
* You can safely retry the same request after a failure without worrying about double charges
* The free retry applies only to the exact call that was paid for — a different request will require its own payment

## References

* [x402 Protocol](https://x402.org)
* [@x402/fetch on npm](https://www.npmjs.com/package/@x402/fetch)
* [@x402/evm on npm](https://www.npmjs.com/package/@x402/evm)
* [USDC on Base](https://basescan.org/token/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913)