How I Built an Instagram API That AI Agents Pay For (x402 + FastAPI + MCP)

#python #ai #showdev #webdev

The Problem: APIs Assume Humans

Most APIs are designed for human developers -- you sign up, get an API key, set up billing, and manage credentials. But AI agents don't have credit cards or email inboxes. They're scripts that run autonomously, sometimes thousands of times per day.

I wanted to build something different: an API where AI agents are the first-class customer, not an afterthought.

What I Built

Social Intel API is an Instagram influencer search endpoint with one unusual property: it accepts USDC micropayments instead of API keys.

Here's the entire authentication flow:

# Step 1: Send request with no auth
curl "https://api.socialintel.dev/v1/search?query=fitness&country=US"

# Server returns HTTP 402:
# { "x402Version": 1, "accepts": [{ "scheme": "exact", "network": "base", "maxAmountRequired": "100000" }] }

# Step 2: Pay $0.10 USDC on Base chain
# Step 3: Retry with X-Payment header

No API key. No signup. No monthly billing. Just pay per request.

The x402 Protocol

x402 is a standard for machine-native payments using HTTP 402 (Payment Required).

The flow:

Client sends request
Server returns 402 with payment schema (amount, wallet, network)
Client pays on-chain (USDC on Base or Solana)
Client retries with X-Payment header containing payment proof
Server verifies and returns data

The whole thing takes ~1-2 seconds including on-chain settlement.

FastAPI Implementation

Using fastapi-x402:

from fastapi import FastAPI
from fastapi_x402 import X402Middleware
import os

app = FastAPI()
app.add_middleware(
    X402Middleware,
    facilitator_url="https://facilitator.payai.network",
    pay_to=os.environ["PAY_TO_ADDRESS"],
)

@app.get("/v1/search")
async def search(query: str, country: str = "US", limit: int = 20):
    results = await fetch_instagram_data(query, country, limit)
    return {"results": results}

One middleware line and any endpoint becomes pay-per-request.

Dynamic Pricing

def _dynamic_price(context) -> int:
    limit = int(context.get("query_params", {}).get("limit", 20))
    if limit <= 20:
        return 100_000  # $0.10 USDC
    return 100_000 + (min(limit, 100) - 20) * 2_000  # +$0.002 per result

MCP Server Integration

I wrapped this as an MCP server so Claude, Cursor, and other AI tools can search Instagram as a native tool.

Claude Desktop config:

{
  "mcpServers": {
    "social-intel": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {"SOCIAL_INTEL_API_URL": "https://api.socialintel.dev"}
    }
  }
}

Ask Claude: "Find 20 fitness influencers in Germany with over 50k followers" -- it handles everything including payment.

What I Learned

The payment mechanics (x402 + fastapi-x402) are only ~20 lines. The real challenges:

Discovery -- How does an agent know your API exists? MCP servers help, but no universal registry yet.
Wallet management -- Agents need pre-loaded USDC. Most agent frameworks don't support this yet.
Error handling -- Return clean 402s, not 500s. Agents need to retry intelligently.

Try It

pip install x402

from x402.client import X402Client

client = X402Client(private_key="YOUR_BASE_WALLET_PRIVATE_KEY", network="base-mainnet")
response = client.get("https://api.socialintel.dev/v1/search", params={"query": "fitness"})
print(response.json())