Paying with x402

x402 uses HTTP 402 Payment Required to tell a client how to pay for a request. The client signs a payment authorization and retries with it. quarry uses x402 v2 to charge USDC per query on Base or Base Sepolia, according to the platform's configured network.

This flow applies when the dataset offers Pay per query. Its discovery contract has a non-null payment field. To use a monthly query quota, follow Agent subscriptions and query through the authenticated agent endpoint.

quarry verifies the authorization, runs the search, then settles payment to the creator's payout wallet before returning the results.

The flow

1. Send a POST to the dataset endpoint with a JSON query body.
2. Read the 402 response. Its payment requirements are in the PAYMENT-REQUIRED response header (base64-encoded JSON): an accepts array with scheme "exact", the CAIP-2 network (e.g. eip155:84532), the asset (USDC contract), and the amount in base units.
3. Sign a USDC payment authorization with your wallet and retry the same request with the base64-encoded payload in PAYMENT-SIGNATURE. The legacy X-PAYMENT header is also accepted.
4. On success, read the search results from the response body. Decode PAYMENT-RESPONSE from base64 JSON to read the transaction hash in transaction.

Client libraries such as @x402/fetch and @x402/axios handle the challenge, signature, and retry. Set endpointUrl to your dataset's endpoint and AGENT_PRIVATE_KEY to your wallet's private key:

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY) });
const fetchWithPay = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPay(endpointUrl, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "your question", top_k: 5 }),
});

Networks

Check the payment.network and payment.caip2 fields of a dataset's discovery contract:

Fund your wallet and sign payments on the network specified by the endpoint. Payments signed for another network are rejected.

Facilitators

A facilitator verifies payment authorizations and submits settlements to the blockchain. quarry uses the Coinbase CDP facilitator when configured, with https://x402.org/facilitator as the fallback.

Your client sends the signed authorization to quarry. quarry handles communication with the facilitator.

Discovery via the x402 Bazaar

Published x402 endpoints include Bazaar discovery metadata with request and response schemas and examples. When the CDP facilitator is configured, it can index these endpoints in Coinbase x402 Bazaar.

The Bazaar MCP server provides search_resources for discovery and proxy_tool_call for paid calls through clients such as @x402/mcp:

https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp

For searches limited to quarry's catalog, use the quarry MCP server.