Guide: Discover & buy through the connector (for agents)

The management MCP (the “connect in Claude” connector, POST /mcp) isn’t just for selling — it’s a full buyer surface too. Once connected, an agent can find data, inspect it for free, fund a wallet, set a budget, and buy — all in one place, without ever hand-building an X-PAYMENT.

New here? The connector authenticates as your account (OAuth or empk_ key) — see Connect in Claude. The raw, accountless x402 flow is in Buy a call; this guide is the connector path.

The whole loop in one minute

1. Discover — search_marketplace → find endpoints (price + free sample inline).
2. Inspect (free) — get_endpoint_sample → the response JSON Schema + a synthetic example + state axes. Decide before paying. Optionally call_endpoint with no payment to take a free trial (real data) or get a price quote.
3. Fund — create_wallet("base") → send USDC to the address → get_wallet shows the balance (this also credits it for spending).
4. Buy — call_endpoint(..., confirmed=true) → pays straight from your wallet → real data + an on-chain receipt.

search_marketplace → get_endpoint_sample → create_wallet → (fund) → get_wallet
   → call_endpoint(confirmed=true) → ✓ data + tx receipt

No buy job required. Funding a wallet and calling call_endpoint with confirmed=true is the whole flow. Buy jobs (create_buy_job) are an optional, advanced feature for delegating a capped budget to a separate agent — see Wallet & budgets. Skip them otherwise.

1 · Discover

• search_marketplace(query?, type?, joinable_on?, limit?) — published, public endpoints. query is free text (name / slug / description / provider / join card); type is api | mcp | dataset (dataset matches API relays that return a download link). Each result carries price_usd, networks, relay_url, the free sample (output_schema + a synthetic example + sample axes), and the fusion metadata (join_card, fusion_ready, joins_with).
• Planning a data fusion? Pass joinable_on — e.g. holding a CRM export with a website column, search_marketplace(joinable_on="domain") returns only listings whose join card declares a matching handle. Read each card (what one record is, exact key formats) and plan the merge before paying. Full step-by-step with a worked example: Data fusion.
• get_endpoint_sample(provider, endpoint) — the full sample for one endpoint, including its join_card (for MCP wrappers, the per-tool input schemas).
• Found nothing? Post the ask with seek_data(what, details?, format?, max_price_usd?, contact?) — anonymous, no account. It lands on the public requested-data board (GET /seek/board) that vendors build against; a clear ask with a price is the fastest way to make missing data exist.

Read the schema, not the example values. When sample.protection is synthetic (the default) the example values are fabricated — only the shape is real. Use output_schema to decide fit; if you need to see real data first, try a free trial (next).

1·5 · Try before you pay (free trials)

Some endpoints offer a free trial: a few real (unpaid) calls, metered per account, so you can validate live data before committing a wallet. You don’t need a separate tool — just call_endpoint with no payment method:

• If a trial is available, the call returns real data at no charge:

  { "ok": true, "trial": true, "remaining": 2,
    "price_usd": "0.02", "data": { …real… },
    "summary": "Free trial — real data, no charge (2 trial call(s) left). Pay $0.02 per call after that." }
  

  remaining is how many free calls are left for your account.
• If no trial is offered (or it’s used up), the same call returns a price quote instead of spending — so you always learn the cost first:

  { "ok": false, "needs_payment": true, "price_usd": "0.02",
    "accepts": [ … ],
    "summary": "Payment required ($0.02). Provide a buy-job `spending_key` or a `signed_payment`. Free trial: not offered." }
  

So the safe pattern is: call once with no payment → if trial you got real data free; if needs_payment you now know the price → fund a wallet, then buy with confirmed=true (below). A buy never happens without explicit intent (a confirmed=true wallet spend, a signed_payment, or a buy-job spending_key).

Trials apply to live, side-effect-free (trial_safe) endpoints whose seller opted in; they don’t apply to MCP-wrapper tool calls. See data samples & free trials.

2 · Get a wallet & fund it

Buying spends USDC from a managed wallet the platform custodies for your account (it signs payments on your behalf — Claude itself can’t sign crypto).

• create_wallet(chain) — base | solana | stellar. Returns the deposit address and a one-time mnemonic/key (save it; shown once).
• Fund it by sending USDC on that chain to the address.
• get_wallet — shows each wallet’s address + on-chain USDC balance. Call this after funding — it scans the deposit and credits your spendable balance.

Full lifecycle — topping up, reading balances, expired jobs, and recovering your funds — is in Wallet & budgets.

3 · Set limits (optional)

You don’t need any of this to buy — a funded wallet + confirmed=true is enough. But you can cap autonomous spend:

• Account policy — set_buy_policy(max_per_call_usd?, confirm_above_usd?). A standing guardrail: a call over max_per_call_usd is refused; a call over confirm_above_usd requires confirmed: true. get_buy_policy reads it; clear: true removes it. This is the simple way to bound spend.
• Buy job (advanced — delegation) — create_buy_job(chain, budget_usd?, max_per_call_usd?, ttl?, label?) mints a capped, disposable spending_key (spk_…) you hand to a separate agent process so it can spend within the budget without your session. Most buyers never need this. Manage with list_buy_jobs / close_buy_job.

Spending real money. A buy moves USDC. Always surface the price and confirm before paying. call_endpoint returns confirmation_required (with the price) when a call exceeds your policy and confirmed isn’t set.

4 · Buy

API relays — call_endpoint

call_endpoint(
  provider, endpoint,
  params?,            # path/query params forwarded to the origin, e.g. {"iso3":"USA"}
  body?,              # request body for POST endpoints
  confirmed?,        # true → pay straight from your funded managed wallet (the simple way)
  signed_payment?,   # OR a base64url X-PAYMENT (bring-your-own wallet)
  spending_key?      # OR a buy-job spk_ (advanced — delegated spend)
)

The simple way: with a funded managed wallet, just call_endpoint(provider, endpoint, params, confirmed=true) — it pays from your wallet. No spending_key, no job. Returns { ok, summary, price_usd, data, receipt } — data is the origin’s real response; receipt has the on-chain tx_hash. params reach the origin via path templating + query string (so {"iso3":"USA"} fills …/countries/{iso3}/profile and appends ?iso3=USA).

MCP wrappers — call_mcp_tool

call_mcp_tool(provider, server, tool, args?, spending_key?|signed_payment?, confirmed?)

Buys one MCP tool call (per-tool priced), settles, and returns the tool result + receipt.

Custody — ways to pay

quote_endpoint(provider, endpoint, tool?) returns the x402 accepts (price, network, payTo, nonce) to sign — no spend.

Buying a dataset

A dataset is bought exactly like any endpoint — call_endpoint — but instead of inline data it returns a download link. (Datasets are API relays with delivery: "download"; see the seller side in Selling datasets.)

1. Find one. search_marketplace(type="dataset") returns only datasets; each result carries delivery: "download", dataset_format, and dataset_license.
2. Preview for free. get_endpoint_sample(provider, endpoint) shows the file’s columns + sample rows (not the link), plus dataset_format and dataset_license. Decide before paying.
3. Buy. call_endpoint(provider, endpoint, spending_key=…) → the result has delivery: "download" and a top-level download_url (plus the on-chain receipt):

   { "ok": true, "delivery": "download", "download_url": "https://…signed…",
     "price_usd": "2.00", "summary": "Bought … — tx 0x…",
     "receipt": { "tx_hash": "0x…" } }
   

4. Download. Fetch download_url — it’s typically short-lived (e.g. a 10-minute presigned URL), so download promptly. If it expires, just buy again (each purchase issues a fresh link). Pricing is per download.

Check the dataset_license before redistributing — datasets often carry usage terms set by the seller.

What it costs

The buyer pays the provider’s price plus a protocol fee (10%, with a small flat floor) — see Rate card. The receipt breaks out provider_amount, fee_amount, and total.

Worked example (Claude, custodial)

“Find a World Bank GDP endpoint, show me the shape, then buy the USA value.”

1. search_marketplace(query="world bank gdp") → finds worldbank-latest-value.
2. get_endpoint_sample("human","worldbank-latest-value") → columns + synthetic row.
3. create_wallet("base") → fund the address with a few dollars of USDC → get_wallet.
4. call_endpoint("human","worldbank-latest-value", params={"country":"USA","indicator":"NY.GDP.MKTP.CD"}, confirmed=true) → real GDP + receipt.tx_hash. (No buy job — it paid straight from your wallet.)

Errors you may see