> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiosk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consumer Guide

> How agents and applications discover APIs, inspect metadata, attach payment, and execute requests through the gateway.

# Consumer Guide

If you are integrating through the Apiosk MCP package in local stdio mode, run `apiosk_get_started` first. It can save a dashboard connect string or create a local wallet, then verify the setup with discovery plus a first execute attempt.

## 1. Discover a listing

Start with the public catalog.

```bash theme={null}
curl "https://gateway.apiosk.com/v1/apis?search=graph&limit=5"
```

If you need category-level browsing, use `GET /types` and `GET /types/:listing_type/v1`.

## 2. Read agent-native metadata

The best entrypoint for agents is:

```bash theme={null}
curl https://gateway.apiosk.com/neural-sync-01/metadata
```

The metadata response exposes:

* operation names
* default operation
* input and output schema hints
* cost and latency metadata
* tags and other agent-facing discovery fields

## 3. Execute using the uniform contract

For default-operation APIs, `POST /execute` accepts raw JSON directly.

```bash theme={null}
curl -X POST https://gateway.apiosk.com/neural-sync-01/execute \
  -H "Content-Type: application/json" \
  -H "x-payment: <x402-proof>" \
  -d '{
    "query": "What does Apiosk do?",
    "context": "Apiosk is a pay-per-call API marketplace for agents."
  }'
```

If you need to choose a non-default operation, use the explicit envelope:

```bash theme={null}
curl -X POST https://gateway.apiosk.com/graph-nexus-api/execute \
  -H "Content-Type: application/json" \
  -H "x-payment: <x402-proof>" \
  -d '{
    "operation": "extract",
    "input": {
      "text": "OpenAI partnered with Microsoft to scale AI infrastructure."
    }
  }'
```

## 4. Handle payment

Paid routes return `HTTP 402` with a machine-readable requirement. Your payer signs that requirement and sends the resulting proof in the `x-payment` header.

The `402` lists one `accepts` entry per settlement network the API is configured for (Base, Polygon, or Arbitrum), all at the same USDC price and with a Base entry always included. Pick the entry you can pay on and name that network in the payment payload, see [Multi-chain Settlement](/guides/multichain).

The gateway does not require API keys for this flow.

If you are using the local MCP package, you normally do not need to build this first step by hand. `apiosk_get_started` configures the local payment state and tells you if the setup is ready or still needs wallet funding.

## 5. Read the normalized response

Successful execute responses are wrapped into a consistent envelope:

```json theme={null}
{
  "status": "success",
  "result": {
    "answer": "Apiosk is a pay-per-call API marketplace for agents."
  },
  "cost": 0.015,
  "latency": 1428,
  "operation": "query",
  "api": "neural-sync-01",
  "upstream_status": 200
}
```

Use passthrough routes only if you deliberately want provider-specific request and response shapes. For generic agent integrations, prefer `GET /metadata` plus `POST /execute`.