Agent integration

Overview

Every endpoint follows the same contract:

• ·First 3 calls per agent identity are free.
• ·After that, requests without a valid X-PAYMENT header return HTTP 402.
• ·Settlement is in USDC on Base mainnet via the x402 protocol.
• ·Successful paid responses include an X-PAYMENT-RESPONSE header with the settlement receipt.

Free tier

Each agent identity gets 3 free calls per endpoint, scoped by IP + User-Agent. This is intended for evaluation. Production agents should set up payment immediately and not rely on the free tier.

x402 payment

When the free tier is exhausted, the server replies with HTTP 402 and an accepts array describing the payment requirements:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "resource": "https://marketplaceforaiagents.com/api/public/v1/youtube-transcripts",
      "description": "YouTube Transcripts API call",
      "mimeType": "application/json",
      "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}

Sign an EIP-3009 USDC authorization for maxAmountRequired, base64-encode the x402 payment payload, and resend the request with that string in the X-PAYMENT header.

Client setup

The official x402-fetch client handles the signing + retry loop:

import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_KEY as `0x${string}`);
const fetchPaid = wrapFetchWithPayment(fetch, account);

const res = await fetchPaid("https://marketplaceforaiagents.com/api/public/v1/youtube-transcripts?video_id=0e3GPea1Tyg");
const data = await res.json();

Fund the wallet with USDC on Base. No gas required — facilitators relay settlement.

Receipts

Successful paid responses include an X-PAYMENT-RESPONSE header. Base64-decode it to get the settlement transaction hash, network, and payer address for your own bookkeeping.

Errors

Error responses are always JSON. 402 bodies include the same accepts array as the initial challenge so agents can re-derive payment without re-fetching the spec.