CurlShip X402 API
USDC payments over the x402 protocol — a self-hosted facilitator settles on-chain; no checkout session, no keys to sign up for.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/curlship-com:curlship-com-x402-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Curlship Com X402 API
version: 1.0.0
contact:
name: CurlShip Support
email: support@curlship.com
url: https://curlship.com
license:
name: Proprietary
description: 'Operations tagged x402 across 2 of this provider''s published API definitions: curlship-com-openapi.json, curlship-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://curlship.com
description: Production
tags:
- name: X402
description: USDC payments over the x402 protocol — a self-hosted facilitator settles on-chain; no checkout session, no keys to sign up for.
paths:
/api/x402/submit:
post:
tags:
- X402
summary: Buy a tier with USDC (x402)
description: '`bronze_lifetime` is $30 USDC once — the listing is owned forever. `platinum` is $49 USDC for a prepaid year (renewals extend from the current expiry, never shorten it). Without `PAYMENT-SIGNATURE` the response is 402 + a `PAYMENT-REQUIRED` quote; send the signed payment and the tier is granted after on-chain settlement. Same URL/email/listing rules as POST /api/submit''s paid path. Rate limit: 30 checkout requests/hour per IP.'
operationId: x402Submit
parameters:
- name: PAYMENT-SIGNATURE
in: header
required: false
description: 'base64 JSON x402 v2 PaymentPayload: the client''s EIP-3009 TransferWithAuthorization signature, echoing the quote as `accepted`.'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
- email
- tier
properties:
url:
type: string
format: uri
example: https://yourapp.com
email:
type: string
format: email
example: you@email.com
tier:
type: string
enum:
- bronze_lifetime
- platinum
example:
url: https://yourapp.com
email: you@email.com
tier: platinum
responses:
'200':
description: Payment settled and granted. `PAYMENT-RESPONSE` (base64 JSON) carries the settlement receipt; `tx_hash` is also in the body.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
tx_hash:
type: string
example: 0x…
listing:
type: object
properties:
id:
type: integer
example: 2076
url:
type: string
format: uri
example: https://yourapp.com/
link:
type: string
format: uri
example: https://yourapp.com/?ref=curlship
description: The URL a visitor is actually sent to — url plus tracking params. Free listings carry ?ref=curlship; paid ones carry the owner's utm_*/ref params (set via POST /api/edit-request tracking).
tier:
type: string
enum:
- free
- bronze
- silver
- gold
- platinum
title:
type:
- string
- 'null'
example: YourApp — ship faster
description:
type:
- string
- 'null'
image:
type:
- string
- 'null'
format: uri
has_badge:
type: boolean
description: True if a dofollow link back to curlship.com was found on the site.
created_at:
type:
- string
- 'null'
format: date-time
example: '2026-10-12T09:04:05Z'
description: When the listing was created, UTC.
category:
oneOf:
- type: object
properties:
slug:
type: string
example: developer-tools
description: The leaf slug when classified that deep, else the group.
name:
type: string
example: Developer tools
group:
type: string
example: developer-tools
description: The top-level group this listing belongs to.
- type: 'null'
description: The listing's category, or null while it is unclassified. Set by the off-server classifier — submitters cannot choose one.
'202':
description: The payment was broadcast but is not confirmed yet. The tx hash rides `PAYMENT-RESPONSE` and `tx_hash` in the body — retry the same PAYMENT-SIGNATURE and the ledger reconciles it; nothing is granted until the payment confirms.
content:
application/json:
schema:
type: object
'400':
description: Malformed input, or a PAYMENT-SIGNATURE that is not a readable x402 v2 exact-EVM payment (v1 envelopes and Permit2-shaped payloads are refused before any verification).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: 'Payment required — or the supplied payment could not be verified/settled (the reason is in `error`). `PAYMENT-REQUIRED` (base64 JSON, x402Version 2) and the body both carry `accepts[0]`: scheme `exact`, the configured network, the USDC asset, the atomic amount, `payTo`, `maxTimeoutSeconds` 300, and `extra` with the EIP-712 token name/version plus an HMAC quote binding. Echo `accepts[0]` back as `accepted` inside a signed PAYMENT-SIGNATURE to pay. A tampered quote re-402s with a fresh one.'
content:
application/json:
schema:
type: object
'409':
description: The payment settled but the grant hit a business conflict — booked refund-needed for a human to reconcile — or a replayed payment already reached a reconciled state.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Rate limit exceeded. Retry-After is the wait in seconds. RateLimit-Policy names the window that was hit. RateLimit repeats that name with r=0 and t equal to Retry-After. Windows: submit 10 per 3600s, verify 30 per 3600s, checkout 30 per 3600s, edit 5 per 3600s per IP, edit-listing 3 per 86400s per listing.'
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
minimum: 1
RateLimit-Policy:
description: 'The window that was hit. Example: "submit";q=10;w=3600.'
schema:
type: string
RateLimit:
description: 'Remaining quota. Example: "submit";r=0;t=120.'
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: The x402 rail is enabled but not serving (misconfiguration or an unhealthy chain probe at startup) — it fails closed instead of minting quotes that could never settle.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://curlship.com
description: Production
/api/x402/feature:
post:
tags:
- X402
summary: Bid on the Featured spot with USDC (x402)
description: 'Same auction as POST /api/feature — `amount_usd` defaults to the current minimum — but payment is a signed x402 authorization, settled on-chain before the bid is marked paid. A losing bid in a concurrent race is booked refund-needed, never silently stranded. Rate limit: 30 checkout requests/hour per IP.'
operationId: x402Feature
parameters:
- name: PAYMENT-SIGNATURE
in: header
required: false
description: base64 JSON x402 v2 PaymentPayload, echoing the quote as `accepted`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
format: uri
example: https://yourapp.com
amount_usd:
type: number
example: 51
description: Your bid in USD, whole cents at most. Omit to bid the current minimum.
example:
url: https://yourapp.com
amount_usd: 51
responses:
'200':
description: Payment settled and granted. `PAYMENT-RESPONSE` (base64 JSON) carries the settlement receipt; `tx_hash` is also in the body.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
tx_hash:
type: string
example: 0x…
listing:
type: object
properties:
id:
type: integer
example: 2076
url:
type: string
format: uri
example: https://yourapp.com/
link:
type: string
format: uri
example: https://yourapp.com/?ref=curlship
description: The URL a visitor is actually sent to — url plus tracking params. Free listings carry ?ref=curlship; paid ones carry the owner's utm_*/ref params (set via POST /api/edit-request tracking).
tier:
type: string
enum:
- free
- bronze
- silver
- gold
- platinum
title:
type:
- string
- 'null'
example: YourApp — ship faster
description:
type:
- string
- 'null'
image:
type:
- string
- 'null'
format: uri
has_badge:
type: boolean
description: True if a dofollow link back to curlship.com was found on the site.
created_at:
type:
- string
- 'null'
format: date-time
example: '2026-10-12T09:04:05Z'
description: When the listing was created, UTC.
category:
oneOf:
- type: object
properties:
slug:
type: string
example: developer-tools
description: The leaf slug when classified that deep, else the group.
name:
type: string
example: Developer tools
group:
type: string
example: developer-tools
description: The top-level group this listing belongs to.
- type: 'null'
description: The listing's category, or null while it is unclassified. Set by the off-server classifier — submitters cannot choose one.
'202':
description: The payment was broadcast but is not confirmed yet. The tx hash rides `PAYMENT-RESPONSE` and `tx_hash` in the body — retry the same PAYMENT-SIGNATURE and the ledger reconciles it; nothing is granted until the payment confirms.
content:
application/json:
schema:
type: object
'400':
description: Malformed input, or a PAYMENT-SIGNATURE that is not a readable x402 v2 exact-EVM payment (v1 envelopes and Permit2-shaped payloads are refused before any verification).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: 'Payment required — or the supplied payment could not be verified/settled (the reason is in `error`). `PAYMENT-REQUIRED` (base64 JSON, x402Version 2) and the body both carry `accepts[0]`: scheme `exact`, the configured network, the USDC asset, the atomic amount, `payTo`, `maxTimeoutSeconds` 300, and `extra` with the EIP-712 token name/version plus an HMAC quote binding. Echo `accepts[0]` back as `accepted` inside a signed PAYMENT-SIGNATURE to pay. A tampered quote re-402s with a fresh one.'
content:
application/json:
schema:
type: object
'409':
description: The payment settled but the grant hit a business conflict — booked refund-needed for a human to reconcile — or a replayed payment already reached a reconciled state.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Rate limit exceeded. Retry-After is the wait in seconds. RateLimit-Policy names the window that was hit. RateLimit repeats that name with r=0 and t equal to Retry-After. Windows: submit 10 per 3600s, verify 30 per 3600s, checkout 30 per 3600s, edit 5 per 3600s per IP, edit-listing 3 per 86400s per listing.'
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
minimum: 1
RateLimit-Policy:
description: 'The window that was hit. Example: "submit";q=10;w=3600.'
schema:
type: string
RateLimit:
description: 'Remaining quota. Example: "submit";r=0;t=120.'
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: The x402 rail is enabled but not serving (misconfiguration or an unhealthy chain probe at startup) — it fails closed instead of minting quotes that could never settle.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No listing found for that URL
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://curlship.com
description: Production
components:
schemas:
Error:
type: object
properties:
ok:
type: boolean
example: false
error:
type: string
example: url is required and must start with http
required:
- ok
- error
externalDocs:
description: Badge guide & instant verify
url: https://curlship.com/badge
x-refined-from:
- curlship-com-openapi.json
- curlship-com-openapi.yml