# Apiosk Gateway

> Pay-per-call API gateway built on the x402 protocol (HTTP 402 + USDC on Base). Agents discover APIs, read machine-readable metadata, and call any API per request - no accounts, API keys, or SDKs. Payment is settled per request via x402 headers.

The gateway is a transparent reverse proxy. Every listed API is reachable at https://gateway.apiosk.com/{api_slug}/{path}. Free endpoints forward immediately; paid endpoints return `402 Payment Required` (x402 v2) with a base64 `PAYMENT-REQUIRED` header plus a JSON body until a valid payment proof is supplied.

## Discovery

- API catalog (JSON): https://gateway.apiosk.com/v1/apis - list every active, verified API with pricing. Supports search, category, sort, order, limit, offset.
- Browse by type: https://gateway.apiosk.com/types - api, dataset, service, connector, skill, product.
- Per-API metadata: https://gateway.apiosk.com/{api_slug}/metadata - agent-native, MCP-style manifest for one API (operations, input/output schemas, pricing, tool annotations).

## Calling an API

- Uniform execution: POST https://gateway.apiosk.com/{api_slug}/execute with body {"operation": "<id | /path | METHOD /path>", "input": { ... }}. Returns {status, result, cost, latency, operation, api, upstream_status}.
- Transparent proxy: ANY https://gateway.apiosk.com/{api_slug}/{path} - forwards your request to the upstream API.

## Payment (x402)

- Protocol: x402 over HTTP 402 (v1 body + v2 header). Settlement asset: USDC on Base.
- A paid request without payment returns 402 with BOTH dialects: a base64 PAYMENT-REQUIRED header (decoded: {x402Version:2, resource, accepts:[{scheme, network (CAIP-2 e.g. eip155:8453), amount (atomic units), asset, payTo, maxTimeoutSeconds, extra}]}) AND a JSON body carrying x402 v1 accepts[] ({scheme, network (bare name e.g. "base"), maxAmountRequired, resource, description, mimeType, payTo, maxTimeoutSeconds, asset, extra}) for x402-fetch SDK clients, plus X-Payment-Amount, X-Payment-Currency: USDC, X-Payment-Protocol: x402.
- Supply the signed payment proof via the PAYMENT-SIGNATURE header (the legacy X-Payment header is still accepted for x402 v1 clients).
- Check spend for a wallet: https://gateway.apiosk.com/v1/balance?address=0x...

## Publishing an API

- Register: POST https://gateway.apiosk.com/v1/apis/register (wallet-signed). See the root discovery document for required fields and the wallet-auth header format.

## Machine-readable manifests

- Well-known index: https://gateway.apiosk.com/.well-known/
- x402 discovery document (all payable resources + payment requirements): https://gateway.apiosk.com/.well-known/x402
- Plugin manifest: https://gateway.apiosk.com/.well-known/ai-plugin.json
- A2A agent card: https://gateway.apiosk.com/.well-known/agent.json
- MCP discovery: https://gateway.apiosk.com/.well-known/mcp.json
- OpenAPI: https://gateway.apiosk.com/openapi.json
- Root discovery JSON: https://gateway.apiosk.com/ (send `Accept: application/json`)