marketplaceforaiagents.com
← Learn

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

QuestionAnswer
Count3 successful calls
ScopeGlobal across all endpoints, not per endpoint
Identity keyHash of IP + User-Agent
When it countsAfter a successful upstream 2xx response
SignalResponse header X-Free-Calls-Remaining
After exhaustionUnpaid 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.

Next steps

Browse the marketplaceIntegration docs