Title: x402 Payments URL Source: https://docs.shipp.ai/api-reference/x402/ Markdown Content: --- description: Pay-per-request access to Shipp using the x402 open payment standard --- [ Skip to content](#what-is-x402) * [ How to Shipp ](../../how-to/) * [ API Reference ](../) * [ Tips for AI Agents ](#tips-for-ai-agents) * [ Guides ](../../platform-guides/) * [ Go To Shipp Dashboard ](https://platform.shipp.ai) * [ Tips for AI Agents ](#tips-for-ai-agents) # x402 Payments Diving Deep? This page is designed for AI Agents & users developing code directly. See [Getting Started](../../) and [Platform Guides](../../platform-guides/) --- ## What is x402?[¶](#what-is-x402 "Permanent link") [x402](https://www.x402.org) 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[¶](#using-x402-with-your-ai-agent "Permanent link") 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](https://www.x402.org) and the Coinbase SDK handle the payment negotiation automatically. --- ## Connecting to Shipp with x402[¶](#connecting-to-shipp-with-x402 "Permanent link") 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`[¶](#post-apiv1connectionsinline "Permanent link") Create and run a connection in one step, paid via x402. ### How it works[¶](#how-it-works "Permanent link") cURL (manual x402 flow)JavaScriptPython `[](#%5F%5Fcodelineno-0-1)# Step 1 — Make the request. You'll get a 402 with payment details. [](#%5F%5Fcodelineno-0-2)curl -i -X POST https://api.shipp.ai/api/v1/connections/inline \ [](#%5F%5Fcodelineno-0-3) -H "Content-Type: application/json" \ [](#%5F%5Fcodelineno-0-4) -d '{ [](#%5F%5Fcodelineno-0-5) "filter_instructions": "Live scores from today'\''s NBA games", [](#%5F%5Fcodelineno-0-6) "since": "2026-01-27T19:41:30Z", [](#%5F%5Fcodelineno-0-7) "limit": 10 [](#%5F%5Fcodelineno-0-8) }' [](#%5F%5Fcodelineno-0-9) [](#%5F%5Fcodelineno-0-10)# Step 2 — Pay using the details from the 402 response, [](#%5F%5Fcodelineno-0-11)# then retry with the payment proof header. [](#%5F%5Fcodelineno-0-12)curl -X POST https://api.shipp.ai/api/v1/connections/inline \ [](#%5F%5Fcodelineno-0-13) -H "Content-Type: application/json" \ [](#%5F%5Fcodelineno-0-14) -H "PAYMENT-SIGNATURE: " \ [](#%5F%5Fcodelineno-0-15) -d '{ [](#%5F%5Fcodelineno-0-16) "filter_instructions": "Live scores from today'\''s NBA games", [](#%5F%5Fcodelineno-0-17) "since": "2026-01-27T19:41:30Z", [](#%5F%5Fcodelineno-0-18) "limit": 10 [](#%5F%5Fcodelineno-0-19) }' ` `[](#%5F%5Fcodelineno-1-1)import { payWithX402 } from "x402-fetch"; [](#%5F%5Fcodelineno-1-2) [](#%5F%5Fcodelineno-1-3)const response = await payWithX402( [](#%5F%5Fcodelineno-1-4) "https://api.shipp.ai/api/v1/connections/inline", [](#%5F%5Fcodelineno-1-5) { [](#%5F%5Fcodelineno-1-6) method: "POST", [](#%5F%5Fcodelineno-1-7) headers: { "Content-Type": "application/json" }, [](#%5F%5Fcodelineno-1-8) body: JSON.stringify({ [](#%5F%5Fcodelineno-1-9) filter_instructions: "Live scores from today's NBA games", [](#%5F%5Fcodelineno-1-10) since: "2026-01-27T19:41:30Z", [](#%5F%5Fcodelineno-1-11) since_event_id: "01KGE1JQG5HMR9A3AQHVZF9W37", [](#%5F%5Fcodelineno-1-12) limit: 10, [](#%5F%5Fcodelineno-1-13) }), [](#%5F%5Fcodelineno-1-14) }, [](#%5F%5Fcodelineno-1-15) { [](#%5F%5Fcodelineno-1-16) walletPrivateKey: process.env.WALLET_PRIVATE_KEY, [](#%5F%5Fcodelineno-1-17) } [](#%5F%5Fcodelineno-1-18)); [](#%5F%5Fcodelineno-1-19) [](#%5F%5Fcodelineno-1-20)const result = await response.json(); [](#%5F%5Fcodelineno-1-21)console.log(result); ` `[](#%5F%5Fcodelineno-2-1)import requests [](#%5F%5Fcodelineno-2-2) [](#%5F%5Fcodelineno-2-3)url = "https://api.shipp.ai/api/v1/connections/inline" [](#%5F%5Fcodelineno-2-4) [](#%5F%5Fcodelineno-2-5)payload = { [](#%5F%5Fcodelineno-2-6) "filter_instructions": "Live scores from today's NBA games", [](#%5F%5Fcodelineno-2-7) "since": "2026-01-27T19:41:30Z", [](#%5F%5Fcodelineno-2-8) "since_event_id": "01KGE1JQG5HMR9A3AQHVZF9W37", [](#%5F%5Fcodelineno-2-9) "limit": 10, [](#%5F%5Fcodelineno-2-10)} [](#%5F%5Fcodelineno-2-11) [](#%5F%5Fcodelineno-2-12)# Step 1 — Make the initial request [](#%5F%5Fcodelineno-2-13)response = requests.post(url, json=payload) [](#%5F%5Fcodelineno-2-14) [](#%5F%5Fcodelineno-2-15)if response.status_code == 402: [](#%5F%5Fcodelineno-2-16) # Step 2 — Extract payment requirements from the 402 response, [](#%5F%5Fcodelineno-2-17) # sign a payment with your wallet, and retry [](#%5F%5Fcodelineno-2-18) payment_details = response.json() [](#%5F%5Fcodelineno-2-19) payment_proof = sign_payment(payment_details) # your x402 wallet logic [](#%5F%5Fcodelineno-2-20) [](#%5F%5Fcodelineno-2-21) headers = { [](#%5F%5Fcodelineno-2-22) "Content-Type": "application/json", [](#%5F%5Fcodelineno-2-23) "PAYMENT-SIGNATURE": payment_proof, [](#%5F%5Fcodelineno-2-24) } [](#%5F%5Fcodelineno-2-25) response = requests.post(url, json=payload, headers=headers) [](#%5F%5Fcodelineno-2-26) [](#%5F%5Fcodelineno-2-27)result = response.json() ` ### Body Params[¶](#body-params "Permanent link") * `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 `[](#%5F%5Fcodelineno-3-1){ [](#%5F%5Fcodelineno-3-2) "filter_instructions": "string (required)", [](#%5F%5Fcodelineno-3-3) "since": "2026-01-27T19:41:30Z", [](#%5F%5Fcodelineno-3-4) "limit": 10, [](#%5F%5Fcodelineno-3-5) "since_event_id": "01KGE1JQG5HMR9A3AQHVZF9W37" [](#%5F%5Fcodelineno-3-6)} ` ### Response (200)[¶](#response-200 "Permanent link") On successful payment and execution, the response mirrors the shape of a standard [Run Connection](../connections-run) response: `[](#%5F%5Fcodelineno-4-1){ [](#%5F%5Fcodelineno-4-2) "connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB", [](#%5F%5Fcodelineno-4-3) "data": [ [](#%5F%5Fcodelineno-4-4) { "...": "shape varies by feed + event data" } [](#%5F%5Fcodelineno-4-5) ] [](#%5F%5Fcodelineno-4-6)} ` ### Response (402 — Payment Required)[¶](#response-402-payment-required "Permanent link") 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[¶](#errors "Permanent link") * **400**: invalid JSON, empty body, or missing `filter_instructions` * **402**: payment required — see above * **500**: unexpected server error --- ## Tips for AI Agents[¶](#tips-for-ai-agents "Permanent link") * **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](../connections-create) and [Run Connection](../connections-run). x402 is an alternative path, not a replacement. Back to top