🤖 x402

Agent Onboarding Guide

How AI agents discover, authenticate, and pay for AllFans API access — no human accounts, no API keys, no prior registration.

Overview

x402 is a protocol for AI agents to discover, authenticate, and pay for API access autonomously — without human accounts, API keys, or prior registration.

AllFans exposes an x402-compatible API that enables AI agents to discover available endpoints, authenticate via crypto wallet signatures, pay per call using USDC microtransactions, and access platform data including events, venues, creators, and tickets.

Agent Flow

The complete agent lifecycle has four steps:

DiscoverFetch the manifest at /.well-known/x402 to find available endpoints, pricing, and authentication requirements.

AuthenticateSign a message with your wallet and send it to POST /api/auth/agent-login. Receive a JWT valid for 7 days.

Request → 402Call any paid endpoint without payment headers. The server responds with 402 Payment Required and the minimum amount.

Pay & RetryInclude x402 payment headers (amount, payment intent, token, recipient, idempotency key, expiry) and retry. On success, you get the data.

1. Discovery

Agents discover AllFans APIs via the standard well-known endpoint:

GET /.well-known/x402

The manifest returns:

Supported chains (Base Sepolia, Arc Testnet)
Accepted tokens (USDC)
All available endpoints with per-route pricing
Authentication requirements (wallet-based JWT)
Required payment headers and their descriptions
Rate limits for each endpoint

DNS alternative:

dig TXT _x402.allfans.io

2. Authentication

No API keys. Agents authenticate using their crypto wallet:

POST /api/auth/agent-login
Content-Type: application/json

{
  "agent_id": "my-agent-v1",
  "wallet_address": "0x...",
  "signature": "0x...",
  "message": "AllFans Agent Auth: <nonce>"
}

On success, the server returns a JWT. Include it in subsequent requests via the Authorization: Bearer <to...de> header.

For persistent access, generate a wallet keypair, fund it with sufficient USDC, and store the private key securely (environment variable, KMS, or TEE).

3. Payment via x402

Each authenticated API call may require a micro-payment. When the server responds with 402 Payment Required, retry with these headers:

Header	Description
`x-402-amount`	Payment amount in USDC (e.g., “0.01”)
`x-402-payment-intent`	Circle Gateway payment intent / spend ID
`x-402-token`	Always “USDC” on AllFans
`x-402-recipient`	AllFans treasury wallet address
`x-402-idempotency-key`	Unique key to prevent double-charge on retry
`x-402-expires-at`	Unix timestamp (5 minutes from creation)

Pricing & Rate Limits

Endpoint	Cost	Rate Limit
`GET /api/events`	0.0001 ETH	100/hour
`GET /api/venues`	0.00005 ETH	200/hour
`GET /api/creators`	0.00005 ETH	200/hour
`POST /api/tickets/purchase`	0.001 ETH	10/hour
`/.well-known/x402`	Free	1000/hour

Agents may prepay for bulk access via the Agent Dashboard (coming soon).

SDK Examples

TypeScript / JavaScript

import { ethers } from "ethers";

class AllFansAgent {
  private wallet: ethers.Wallet;
  private baseUrl = "https://api.allfans.io";
  private jwt: string | null = null;

  constructor(privateKey: string) {
    this.wallet = new ethers.Wallet(privateKey);
  }

  async discover() {
    const res = await fetch(`${this.baseUrl}/.well-known/x402`);
    return res.json();
  }

  async authenticate() {
    const message = `AllFans Agent Auth: ${Date.now()}`;
    const signature = await this.wallet.signMessage(message);
    const res = await fetch(`${this.baseUrl}/api/auth/agent-login`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        walletAddress: this.wallet.address,
        signature,
        message,
        agent_id: "my-agent",
      }),
    });
    const data = await res.json();
    this.jwt = data.data?.token;
  }

  async getEvents() {
    const res = await fetch(`${this.baseUrl}/api/events`, {
      headers: {
        Authorization: 'Bearer ' + this.jwt,
        "Content-Type": "application/json",
      },
    });
    if (res.status === 402) {
      const body = await res.json();
      const minAmount = body._funding_required?.suggestedAmount || "0.01";
      const retry = await fetch(`${this.baseUrl}/api/events`, {
        headers: {
          Authorization: 'Bearer ' + this.jwt,
          "x-402-amount": minAmount,
          "x-402-payment-intent": `spend_${Date.now()}`,
          "x-402-token": "USDC",
          "x-402-recipient": "0x...",
          "x-402-idempotency-key": `idemp_${Date.now()}`,
          "x-402-expires-at": String(
            Math.floor((Date.now() + 5 * 60 * 1000) / 1000)
          ),
        },
      });
      return (await retry.json()).data;
    }
    return (await res.json()).data;
  }
}

Security Considerations

Wallet Security: Agent private keys must be stored securely (HSM, TEE, or encrypted environment variables). Never hardcode keys in source code.
Idempotency: Always generate unique idempotency keys for each payment. Reusing a key after a failed response (network error) is safe; reusing after a success is not.
Expiry: Payment intents expire after 5 minutes. Generate fresh ones if retrying after a delay.
Rate Limits: Respect per-endpoint rate limits. Agents that exceed limits receive 429 Too Many Requests.
Funds: Ensure your agent wallet maintains sufficient USDC balance for expected API usage.