# How the x402 free tier and agent identity work

Marketplace for AI Agents gives every agent identity 3 free calls across all endpoints before x402 payment kicks in. Here is how identity is scoped, how to read X-Free-Calls-Remaining, and how to graduate to paid USDC calls without surprise 402s.

Marketplace for AI Agents gives every agent identity 3 successful calls total, global across all endpoints, before x402 payment is required. Identity is a hash of IP + User-Agent. After the third successful call, the next unpaid request returns HTTP 402 Payment Required with an accepts[] payload.

The free tier is for evaluation, not a production quota. Production agents should budget and sign payments instead of relying on free calls.

## What 3 free calls means

| Question | Answer |
| --- | --- |
| Count | 3 successful calls |
| Scope | Global across all endpoints, not per endpoint |
| Identity key | Hash of IP + User-Agent |
| When it counts | After a successful upstream 2xx response |
| Signal | Response header X-Free-Calls-Remaining |
| After exhaustion | Unpaid request → HTTP 402 with accepts[] |

A 400 missing_required_parameters or 404 unknown_endpoint does not consume a free call. Only successful upstream responses count.

## How to read X-Free-Calls-Remaining

Successful free-tier responses include the X-Free-Calls-Remaining header. It shows how many free calls are left after this one.

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

HTTP/1.1 200 OK
X-Free-Calls-Remaining: 2
Content-Type: application/json

{ ... }
```

```ts
const remaining = res.headers.get("X-Free-Calls-Remaining");
if (remaining !== null) {
  console.log("Free calls left:", remaining);
}
```

If the header is absent and the response is 200, the call was likely paid (X-PAYMENT-RESPONSE present) or the free tier was already exhausted.

## What happens on call 4 without payment

After the free tier is exhausted, an unpaid request returns 402 with a single accepts entry describing the required payment.

```json
{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxAmountRequired": "5000",
    "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
    "resource": "https://marketplaceforaiagents.com/api/public/v1/google-search",
    "extra": { "name": "USDC", "version": "2" }
  }]
}
```

The agent signs an EIP-3009 USDC authorization on Base, base64-encodes the x402 payload, and resends the request with X-PAYMENT. A paid 200 carries X-PAYMENT-RESPONSE, a base64 receipt.

Read the protocol explainer for the full handshake: https://marketplaceforaiagents.com/learn/x402-protocol-explained.

## Agent fleet design

Because identity is scoped by IP + User-Agent, agents that share an egress IP and a stable User-Agent share one free-tier counter. Rotating User-Agent strings to farm free calls is a bad idea: it makes your traffic look abusive and breaks the predictable identity you need for budgeting.

- Use a stable, descriptive User-Agent that identifies the agent runtime or project.
- If multiple agents share an egress IP, treat the free tier as one shared evaluation budget.
- Do not design production flows that assume free calls are available.
- Use a dedicated payer wallet per environment (mainnet vs Sepolia smoke tests).

## Evaluation recipe

Spend the 3 free calls deliberately. Discovery fetches like /.well-known/x402, /api/public/v1/catalog.json, and /api/public/v1/openapi.json do not consume the free tier because they are not paid endpoint calls.

- 1) Read discovery: GET https://marketplaceforaiagents.com/.well-known/x402
- 2) Read catalog + OpenAPI: /api/public/v1/catalog.json and /api/public/v1/openapi.json
- 3) Probe one paid endpoint with a simple required param, e.g. /api/public/v1/google-search?q=x402+free+tier
- 4) Check X-Free-Calls-Remaining and confirm the response shape matches the documented results key
- 5) Run the same call with ?network=base-sepolia to test the 402 → payment → 200 path on testnet USDC
- 6) Promote to Base mainnet only after the Sepolia smoke test passes

```bash
# Discovery (no free-tier cost)
curl -s https://marketplaceforaiagents.com/.well-known/x402 | jq '.endpoints[0].freeTier'
# → 3

# First endpoint probe (counts as 1 of 3)
curl -si "https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+free+tier"

# Sandbox probe (still counts against free tier unless already exhausted)
curl -si "https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+free+tier&network=base-sepolia"
```

For the payment-signing smoke test, see https://marketplaceforaiagents.com/learn/x402-base-sepolia-smoke-test.

## Related entrypoints and guides

- Manifest: https://marketplaceforaiagents.com/.well-known/x402
- Catalog: https://marketplaceforaiagents.com/api/public/v1/catalog.json
- OpenAPI: https://marketplaceforaiagents.com/api/public/v1/openapi.json
- MCP: https://marketplaceforaiagents.com/mcp
- Docs: https://marketplaceforaiagents.com/docs
- Browse: https://marketplaceforaiagents.com/marketplace
- Protocol explainer: https://marketplaceforaiagents.com/learn/x402-protocol-explained
- Budget before signing: https://marketplaceforaiagents.com/learn/budget-x402-api-calls
- Sepolia smoke test: https://marketplaceforaiagents.com/learn/x402-base-sepolia-smoke-test
- MCP connect guide: https://marketplaceforaiagents.com/learn/mcp-x402-marketplace
- Agent discovery: https://marketplaceforaiagents.com/learn/how-ai-agents-discover-apis

Free calls are for proving the endpoint works. Paid calls are for production agents that need deterministic access.

Canonical HTML: https://marketplaceforaiagents.com/learn/x402-free-tier-agent-identity