Skip to main content

​
Apiosk Gateway

The Apiosk gateway is a pay-per-call API surface for agents and applications. Consumers discover APIs, inspect machine-readable metadata, receive an HTTP 402 payment challenge when required, attach an x-payment proof, and execute calls through a uniform contract.

​
At a glance

The gateway acts as a public x402 payment boundary. A client requests execution, receives pricing in a 402 Payment Required response when the route is paid, settles in USDC on a supported network, Base and Solana are live, Polygon and Arbitrum coming soon, retries with a proof, and then receives the upstream result through the same public surface. See Multi-chain Settlement. x402 crypto rail flow This is the fastest way to understand the model:
  1. The agent makes a normal request to the gateway.
  2. The gateway returns HTTP 402 plus pricing when payment is required.
  3. The client settles on-chain and attaches the proof in x-payment.
  4. The gateway verifies the proof, forwards the call, and returns data.

​
Ways to integrate

Pick the path that fits where your software runs. Same payment flow, four ways to wire it up.
PathBest forGuide
Gateway API (direct HTTP)Maximum control over headers, retries, and the raw 402 loop/guides/consumers · /guides/execute
Remote MCPChatGPT and agent clients, add the URL, OAuth once, run paid tools/guides/mcp-clients
JavaScript SDK (@apiosk/sdk)Node backends that want typed 402 errors and auto-pay/guides/sdk
Gateway SkillCoding agents (Claude Code, Codex) running paid calls from a shell/guides/gateway-skill
If you sell access instead of buying it, gating a skill, download, or service behind payment, see Payment Checks.

​
GPT-native MCP quickstart

If you are integrating Apiosk into ChatGPT or another remote MCP client, do not start with raw gateway calls. Start with the hosted MCP endpoint instead: 
https://mcp.apiosk.com/mcp
The remote MCP flow is:
  1. Add the hosted MCP endpoint to your GPT client.
  2. Complete hosted OAuth with your Apiosk dashboard account.
  3. Use discovery and paid tools from the same chat session.
Important behavior:
  • No handoff file is required for GPT-native MCP clients.
  • Direct gateway plus X-Apiosk-Connect-Token is still the right path for manual HTTP runtimes and raw x402 flows.
  • Full setup instructions live in /guides/mcp-clients.

​
Public routes that matter

RoutePurpose
GET /typesDiscover listing groups.
GET /v1/apisSearch and paginate public listings.
GET /v1/apis/:slugInspect one public listing and its endpoint docs.
GET /:api_slug/metadataFetch MCP-style metadata and operation hints.
POST /:api_slug/executeExecute through the agent-native contract.
POST /v1/apis/registerPublish a community API listing.

​
How the public flow works

  1. Discover an API from the catalog.
  2. Read /:api_slug/metadata to understand the default operation, schemas, price, and tags.
  3. Call /:api_slug/execute.
  4. If the route is paid, handle the 402 Payment Required response and attach an x-payment proof.
  5. Receive a normalized response envelope with result, cost, latency, and status.

​
What these docs do not expose

  • settlement and payout topology
  • operator controls
  • replay and anti-abuse implementation details
  • managed wallet or session internals
  • internal forwarding behavior that is not part of the public contract
Use the guides for integration patterns and the API reference for the route-level contract.