Quickstart for agents

Add https://quarry.market/api/mcp to your agent as a remote MCP server (setup per client). Searching is free and needs no account; full, cited passages are paid per question, with a monthly subscription or a USDC wallet.

Start free: search

Call search with your question. It returns the datasets that best match, each with a short preview of its best passage, its price and a next hint. Then call ask with a result's username and slug to get the full passages, as below.

Start with a subscription

1. Open Subscriptions. Either connect your agent (copy the MCP URL under Connected agents, add it to an OAuth-capable client and approve access), or create an API key for code.
2. Use search, then get_dataset and quote_access for your chosen dataset.
3. If a subscription is needed, call request_subscription with the returned dataset and offer IDs. Review and pay through the Checkout link.
4. Wait until quote_access returns included, then call ask with a unique request_id.

See Agent subscriptions for the request example, quota rules, payment confirmation, and cancellation.

Start with x402

For the steps below, choose a dataset that offers pay per query. You need a wallet with enough USDC to cover the query price on the endpoint's network. quarry supports Base and Base Sepolia. For Base Sepolia, you can get testnet USDC from Circle's faucet.

The JavaScript example below reads the wallet's private key from the AGENT_PRIVATE_KEY environment variable.

1. Find an endpoint

Choose a dataset from Explore, or find one with the MCP search tool. Agents that speak MCP can also pay inside MCP: see x402 inside MCP. Each listing links to an endpoint with this format:

https://quarry.market/{username}/{slug}

2. Read the discovery contract

A free GET returns the dataset's request and response schemas, price, and network. Replace the example URL with your chosen endpoint:

curl https://quarry.market/alice/sec-filings

The response includes:

{
  "name": "SEC filings 2025",
  "payment": { "protocol": "x402", "price_usdc": 0.01, "network": "base", "caip2": "eip155:8453" },
  "request": {
    "method": "POST",
    "url": "https://quarry.market/alice/sec-filings",
    "content_type": "application/json",
    "body": {
      "query": "string, required, max 2000 chars",
      "top_k": "integer, optional, 1-20, default 5"
    }
  }
}

If payment is null, x402 is disabled for this dataset. Follow its subscription_offer and agent_mcp fields instead; the public dataset POST does not consume a subscription quota.

3. Request the payment requirements

For a published x402 dataset that is ready to query, a POST without payment returns HTTP 402 Payment Required. The PAYMENT-REQUIRED response header carries base64-encoded JSON with an accepts array specifying the payment scheme, CAIP-2 network, asset, and amount:

curl -i -X POST https://quarry.market/alice/sec-filings \
  -H "content-type: application/json" \
  -d '{ "query": "revenue guidance for 2025" }'

4. Pay automatically with @x402/fetch

Install @x402/fetch, @x402/evm, and viem in your client project. The fetch wrapper reads the 402, signs a USDC payment authorization, and retries the request:

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("https://quarry.market/alice/sec-filings", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "revenue guidance for 2025", top_k: 5 }),
});

const data = await res.json();
console.log(data.results);

On success, the response body contains ranked results. Decode the PAYMENT-RESPONSE header from base64 JSON to read the settlement's transaction hash in its transaction field. For unsuccessful responses, see Error codes.

Next steps