/docs/quickstart

Quickstart: pay for an API call with x402

Call a marketplace endpoint, get an HTTP 402 challenge, sign USDC on Base and retry — with @x402/fetch, @x402/axios, Python httpx, or raw HTTP.

Every endpoint is GET https://marketplaceforaiagents.com/api/public/v1/{slug}. The first 3 calls per agent identity are free; after that the server answers 402 Payment Required with exact x402 terms (USDC on Base, network eip155:8453). Current price: $0.003 USDC per step (3000 atomic units, 6 decimals) during the promotion ending 2026-11-01T05:00:00Z; the regular price is $0.005. Always trust the amount in the live 402.

Use the x402 v2 packages (@x402/*). The legacy v1 packages x402-fetch and x402-axios still exist and still work against this gateway, but new integrations should use @x402/fetch / @x402/axios.

TypeScript (fetch)

// npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await fetchWithPayment("https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+protocol");
console.log(await res.json());
const pr = res.headers.get("PAYMENT-RESPONSE");
if (pr) console.log(decodePaymentResponseHeader(pr));

For the sandbox use network "eip155:84532" and https://marketplaceforaiagents.com/api/sandbox/v1/google-search?q=test (see /docs/sandbox).

TypeScript (axios)

// npm i @x402/axios @x402/evm viem axios
import axios from "axios";
import { wrapAxiosWithPaymentFromConfig } from "@x402/axios";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const { data, headers } = await api.get("https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+protocol");
console.log(data, headers["payment-response"]);

Python (httpx)

python

# pip install "x402[httpx,evm]" eth-account
import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http import x402HTTPClient
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

async def main():
    client = x402Client()
    register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"])))
    async with x402HttpxClient(client) as http:
        r = await http.get("https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+protocol")
        await r.aread()
        print(r.json())
        settle = x402HTTPClient(client).get_payment_settle_response(lambda n: r.headers.get(n))
        print(settle)

asyncio.run(main())

Raw HTTP

1. GET the endpoint with no payment header.
2. Receive 402 with the requirements in the PAYMENT-REQUIRED header (base64 JSON) and in the JSON body (accepts[] for v2, acceptsV1[] for v1).
3. Sign an EIP-3009 USDC authorization for one entry of accepts[] (amount, asset, payTo, network).
4. Retry the same URL with PAYMENT-SIGNATURE: <base64 v2 PaymentPayload> (or X-PAYMENT for v1).
5. Read the settlement receipt from PAYMENT-RESPONSE (v2) or X-PAYMENT-RESPONSE (v1).

bash

curl -si "https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+protocol" | grep -i payment-required

CDP wallets

To keep keys off your machine, use a Coinbase Developer Platform Server Wallet account as the viem-compatible signer in place of privateKeyToAccount. See https://docs.cdp.coinbase.com/ for how to create and export that account object.