Skip to main content

​
What is AgentKit?

World AgentKit is a toolkit that lets AI agents prove they are backed by a real, verified human via World ID. When integrated with x402, it enables a free trial path: agents registered in World’s AgentBook can access Exa’s /search and /contents endpoints without paying USDC. This works alongside the standard x402 payment flow. If an agent has free trial uses remaining, it gets results for free. Once exhausted, it falls back to the normal USDC payment path.
AgentKit free trial and x402 payment are both bypassed if your request includes an x-api-key or Authorization: Bearer header. The normal API key billing flow takes priority.

​
How it works

When a client hits /search or /contents without an API key, Exa responds with 402 Payment Required. The response includes an agentkit extension in the PAYMENT-REQUIRED header containing a CAIP-122 (Sign-In with Ethereum) challenge. The agent signs this challenge with its registered wallet, and Exa verifies:
  1. Signature check — validates the SIWE signature against the wallet address (supports both EOA via EIP-191 and smart contract wallets via ERC-1271)
  2. AgentBook lookup — resolves the wallet to an anonymous humanId via the AgentBook contract on World Chain (eip155:480), confirming a unique verified human delegated their identity to this agent
  3. Usage check — if the human still has free trial uses remaining, access is granted; otherwise, falls back to requiring USDC payment

​
Quickstart

​
1. Register your agent in AgentBook

This is a one-time setup. You need the World App with a verified identity. 
npx @worldcoin/agentkit-cli register <your-agent-wallet-address>
The CLI triggers a World App verification flow, then submits a registration transaction on World Chain. Once complete, any server using AgentKit can look up your wallet and confirm it is backed by a real person.

​
2. Send a request (get the challenge)

curl -s -D - -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "fusion energy breakthroughs", "numResults": 5}'
The 402 response includes an agentkit extension inside the decoded PAYMENT-REQUIRED payload: 
{
  "x402Version": 2,
  "accepts": [ ... ],
  "extensions": {
    "agentkit": {
      "info": {
        "version": "1",
        "statement": "Verify your agent is backed by a real human to access Exa",
        "domain": "api.exa.ai",
        "uri": "https://api.exa.ai/search",
        "nonce": "abc123...",
        "issuedAt": "2026-04-11T01:30:00.000Z",
        "resources": ["https://api.exa.ai/search"]
      },
      "supportedChains": [
        { "chainId": "eip155:480", "type": "eip191" },
        { "chainId": "eip155:480", "type": "eip1271" }
      ],
      "schema": { ... },
      "_options": {
        "statement": "Verify your agent is backed by a real human to access Exa",
        "mode": { "type": "free-trial", "uses": 20 },
        "network": "eip155:480"
      }
    }
  }
}

​
3. Sign the challenge and resubmit

Construct a SIWE message from the info fields (domain, uri, nonce, statement, etc.), sign it with your registered agent wallet using one of the supportedChains types, and send it in the agentkit header (base64-encoded JSON): 
curl -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "agentkit: <base64-encoded-signed-challenge>" \
  -d '{"query": "fusion energy breakthroughs", "numResults": 5}'
If the agent is verified and has free trial uses remaining, Exa returns 200 with search results — no payment needed.

​
Using the AgentKit x402 skill

Instead of implementing the challenge-response flow manually, add the agentkit-x402 skill to your AI agent: 
npx skills add worldcoin/agentkit agentkit-x402
This skill automatically handles the full flow when the agent encounters a 402 response with an AgentKit extension.

​
Free trial details

  • Each verified human gets a fixed number of free requests across all agents they back
  • Usage is tracked per human per endpoint (/search and /contents are counted separately)
  • Two agents backed by the same human share the same counter
  • Once free trial uses are exhausted, the agent falls back to the standard x402 payment flow
  • The same 10-result cap applies to free trial requests on /search
  • The free trial counter is not currently exposed in the API response — when uses are exhausted, the server responds with a standard 402 without granting free access

​
Supported endpoints

Endpointx402 PaymentAgentKit Free Trial
/searchYesYes
/contentsYesYes
/answerNoNo
/researchNoNo
/findSimilarNoNo

​
Network details

PropertyValue
AgentBook chainWorld Chain
Chain ID (CAIP-2)eip155:480
VerificationAgentBook contract on World Chain
Supported wallet typesEOA (EIP-191) and smart contract wallets (ERC-1271)

​
FAQ

Yes. The PAYMENT-REQUIRED response includes both payment pricing and the AgentKit challenge. Your client can choose either path. If free trial uses are exhausted, the agent can fall back to paying with USDC.
The AgentKit verification fails silently and the request is treated as a standard 402 — your agent can still pay with USDC via the normal x402 flow.
No. Usage is tracked per human (via the anonymous humanId from AgentBook), not per wallet. Two agents backed by the same World ID share the same counter.
USDC payments settle on Base (eip155:8453). AgentKit verification uses World Chain (eip155:480) for AgentBook lookups. These are independent — AgentKit doesn’t require any on-chain payment.
Both EOA (externally owned accounts) using EIP-191 signatures and smart contract wallets (e.g. Coinbase Smart Wallet, Safe) using ERC-1271. See the World AgentKit SDK reference for details.

​
Resources