# 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` with `X-Payment-*` headers until a valid x402 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. Settlement asset: USDC on Base.
- A paid request without payment returns 402 with X-Payment-Amount, X-Payment-Currency: USDC, and X-Payment-Protocol: x402.
- Supply payment proof via the X-Payment header.
- 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`)