x402 Payments

What is x402?¶

x402 is an open, internet-native payment standard built on top of HTTP. Instead of signing up for accounts, managing API keys, or buying credits in advance, an x402 client simply makes a request — and if payment is required, the server responds with HTTP 402 Payment Required along with pricing details. The client then pays instantly with stablecoins and retries the request. Done.

Why it matters for AI agents:

• No accounts or API keys — your agent can discover and pay for services on the fly
• Micropayments — pay fractions of a cent per request; no subscriptions or prepaid credits
• Zero friction — money moves at the speed of an HTTP request
• Agent-native — designed for programmatic, machine-to-machine commerce

Using x402 with Your AI Agent¶

The x402 flow is simple enough that any HTTP-capable agent can participate:

1. Agent sends a request to a paid endpoint
2. Server responds with 402 Payment Required, including payment details (price, accepted networks, payment address) in the response headers/body
3. Agent constructs and signs a payment using a funded wallet
4. Agent retries the request with the payment proof attached in the PAYMENT-SIGNATURE header
5. Server verifies the payment and returns the data

Your agent needs a crypto wallet (e.g., on Base) funded with USDC to participate. Libraries like x402-next and the Coinbase SDK handle the payment negotiation automatically.

Connecting to Shipp with x402¶

Shipp supports x402 on the inline connection endpoint, enabling your agent to create a connection and retrieve real-time data in a single pay-per-request call — no API key required.

POST /api/v1/connections/inline¶

Create and run a connection in one step, paid via x402.

How it works¶

# Step 1 — Make the request. You'll get a 402 with payment details.
curl -i -X POST https://api.shipp.ai/api/v1/connections/inline \
  -H "Content-Type: application/json" \
  -d '{
    "filter_instructions": "Live scores from today'\''s NBA games",
    "since": "2026-01-27T19:41:30Z",
    "limit": 10
  }'

# Step 2 — Pay using the details from the 402 response,
#          then retry with the payment proof header.
curl -X POST https://api.shipp.ai/api/v1/connections/inline \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <payment-proof>" \
  -d '{
    "filter_instructions": "Live scores from today'\''s NBA games",
    "since": "2026-01-27T19:41:30Z",
    "limit": 10
  }'

import { payWithX402 } from "x402-fetch";

const response = await payWithX402(
  "https://api.shipp.ai/api/v1/connections/inline",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      filter_instructions: "Live scores from today's NBA games",
      since: "2026-01-27T19:41:30Z",
      since_event_id: "01KGE1JQG5HMR9A3AQHVZF9W37",
      limit: 10,
    }),
  },
  {
    walletPrivateKey: process.env.WALLET_PRIVATE_KEY,
  }
);

const result = await response.json();
console.log(result);

import requests

url = "https://api.shipp.ai/api/v1/connections/inline"

payload = {
    "filter_instructions": "Live scores from today's NBA games",
    "since": "2026-01-27T19:41:30Z",
    "since_event_id": "01KGE1JQG5HMR9A3AQHVZF9W37",
    "limit": 10,
}

# Step 1 — Make the initial request
response = requests.post(url, json=payload)

if response.status_code == 402:
    # Step 2 — Extract payment requirements from the 402 response,
    #          sign a payment with your wallet, and retry
    payment_details = response.json()
    payment_proof = sign_payment(payment_details)  # your x402 wallet logic

    headers = {
        "Content-Type": "application/json",
        "PAYMENT-SIGNATURE": payment_proof,
    }
    response = requests.post(url, json=payload, headers=headers)

result = response.json()

Body Params¶

• filter_instructions (string, required): A natural-language description of the data you want (e.g., sport, league, scope, fields).
• since (string, ISO 8601 / RFC 3339, optional): A reference time to pull results starting from. Default: 48 hours ago
• limit (int, optional): a limit of events to return. Default: 100
• since_event_id (ULID, optional): the last id received, only sends data from newer events. Limit and since are respected. Causes events to be ordered asc by wall_clock_start time

{
  "filter_instructions": "string (required)",
  "since": "2026-01-27T19:41:30Z",
  "limit": 10,
  "since_event_id": "01KGE1JQG5HMR9A3AQHVZF9W37"
}

Response (200)¶

On successful payment and execution, the response mirrors the shape of a standard Run Connection response:

{
  "connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB",
  "data": [
    { "...": "shape varies by feed + event data" }
  ]
}

Response (402 — Payment Required)¶

Returned when the request does not include valid payment proof. The response body and headers contain everything your agent needs to construct a payment:

• Price — the cost for this request
• Accepted networks — which blockchains and tokens are supported (e.g., USDC on Base)
• Payment address — where to send the funds

Errors¶

• 400: invalid JSON, empty body, or missing filter_instructions
• 402: payment required — see above
• 500: unexpected server error

Tips for AI Agents¶

• Use an x402-compatible library to handle the 402 → pay → retry loop automatically. This keeps your agent logic clean.
• Fund your agent wallet with a small amount of USDC on Base. Micropayments mean a few dollars takes you very far.
• No API key needed — the x402 endpoint is fully self-service. Your agent can start using Shipp the moment it has a funded wallet.
• Combine with standard API access — if you prefer API-key-based billing, see Create Connection and Run Connection. x402 is an alternative path, not a replacement.