Skip to main content

​
What is x402?

x402 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

ActionEndpointCostNotes
Create an indexPOST /beta/indexes/agent1.00 USDCFirst 3 indices per agent are free; charged from the 4th onwards
Get index informationGET /beta/indexes/:indexId0.01 USDCFree for the index owner; charged for any other caller
List indexesGET /beta/indexes/agent0.01 USDC per indexCharged based on the number of indexes returned

​
Using the MCP (no action needed)

If you are running the Indexy MCP Server 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.
API Key (INDEXY_API_KEY) mode does not support x402 payments. Use Web3 wallet authentication to enable automatic payments via the MCP.

​
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

npm install @x402/evm @x402/fetch viem

​
Example (Node.js / TypeScript)

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, Bridge, 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