# Integration docs

## Trust / verified

- **Settlement-verified on PayAPI Market** — `payment_verified: true`, `status: live`. A third party paid real USDC on Base and received a real response. Listing: https://payapi.market/api/marketplace-for-ai-agents (agent API: https://payapi.market/agent/get?id=marketplace-for-ai-agents).
- **Listed / routable on agent402.tools** — listed with `routable: true`, `health: 1`, origin `https://marketplaceforaiagents.com`, 51 tools.
- **Settle only on upstream 2xx** — a failed upstream call returns `502 upstream_error` and is not charged.
- **51 endpoints** — 38 single engines + 13 named intent chains. Intent price is $0.003 x steps and the billed chain is advertised in the 402 response.
- **Public MCP** — https://marketplaceforaiagents.com/mcp. Payment is the auth; there is no OAuth and no signup.
- **Payee and asset** — payTo `0x05e82e03753c7bc99fb24d10a876cce53f24b7b7`, USDC on Base `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. Allowlist both before signing.

x402 Bazaar validate passes; the CDP discovery index may lag (CDP issue #2207).

## 0. If your agent was asked to find X

You were told to "get a YouTube transcript", "search the web", "check flight prices", "look up a product". Cold start:

1. `GET https://marketplaceforaiagents.com/api/public/v1/catalog.json` — every endpoint, params, and result key in one JSON fetch.
2. Or connect the MCP server at `https://marketplaceforaiagents.com/mcp` (no auth) and call `list_apis`.
3. Call the endpoint with no payment header — the first 3 calls per identity are free.
4. When the free tier is gone the same call returns 402 with exact x402 payment requirements.

## 1. Discover

```bash
curl -s https://marketplaceforaiagents.com/.well-known/x402
curl -s https://marketplaceforaiagents.com/api/public/v1/catalog.json
```

## 2. Call unpaid (free tier)

```bash
curl -s "https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+protocol"
```

Identity is a hash of IP + User-Agent. 3 free calls per identity in total across all endpoints (not per endpoint). Successful free-tier responses carry an `X-Free-Calls-Remaining` header.

Who gets free calls:

- Recognised agent runtimes (Claude, GPT, Grok, Gemini, LangChain, MCP, Cursor, x402-fetch, and similar User-Agents): 3 free calls per identity, no shared budget.
- Unknown/generic clients: 3 free calls per identity, drawn from a site-wide budget of 100 successful free calls per UTC day. When that budget is spent, unpaid calls return `402` with `error: free_tier_global_exhausted`.
- Crawlers, health checks, monitoring tools and browsers: no free calls — always `402` with full payment requirements.

## 3. Handle 402

```json
{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "3000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
      "resource": "https://marketplaceforaiagents.com/api/public/v1/{slug}"
    }
  ]
}
```

## 4. Pay and retry

```ts
import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http() });
const pay = wrapFetchWithPayment(fetch, wallet);

const res = await pay("https://marketplaceforaiagents.com/api/public/v1/google-news?q=base+usdc");
const data = await res.json();
```

## 5. Sandbox

Add `network=base-sepolia` to any endpoint. It requires testnet USDC (`0x036CbD53842c5426634e7929541eC2318f3dCF7e`) and returns mock data in the documented shape, so integration tests cost nothing real.

## Errors

- `400 missing_required_parameters` — body lists the missing names.
- `402 payment_required` — body carries `accepts`.
- `404 unknown_endpoint` — re-read `/.well-known/x402`.
- `502 upstream_error` — upstream provider failed; the call is not charged.

PayAPI listing: https://payapi.market/api/marketplace-for-ai-agents

Canonical HTML: https://marketplaceforaiagents.com/docs