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

# Gateway API Reference: Endpoints and Authentication

> Base URL, authentication schemes, error response format, and a complete endpoint summary for the Meterlane Agent Gateway API reference.

The Meterlane Agent Gateway exposes a single base URL that handles both x402 paid proxy traffic and Bearer-authenticated management calls. You send unpaid requests to a route URL, receive a `402` with payment requirements, sign a USDC payment, and retry — the gateway validates, settles, and forwards your request to the upstream service. Management endpoints let you create and configure those routes using a dashboard-issued API key.

## Base URL

| Environment | URL                             |
| ----------- | ------------------------------- |
| Production  | `https://gateway.meterlane.app` |

## Authentication

The gateway uses two distinct authentication schemes depending on the endpoint you are calling.

**Management endpoints (`/api/*`)** require a Bearer token issued from your Meterlane dashboard:

```http theme={null}
Authorization: Bearer bp_live_…
```

**Paid proxy routes (`/gateway/:orgSlug/*`)** use the x402 `X-PAYMENT` header instead of Bearer. You do not need an API key to call a paid route — you need a valid signed payment payload. On the first (unpaid) request you can omit the header entirely; the gateway returns a `402` with the requirements you need to construct it.

```http theme={null}
X-PAYMENT: <base64-encoded signed payment payload>
```

<Note>
  Never send a Bearer token on proxy route requests. The `/gateway/:orgSlug/*` paths authenticate exclusively through x402. See the [Payments](/api-reference/gateway-payments) page for the full two-step flow.
</Note>

## Error Format

All error responses share a consistent JSON shape:

```json theme={null}
{
  "code": "ROUTE_NOT_FOUND",
  "message": "No active route matched the requested path.",
  "requestId": "req_01hx9z2k3m4n5p6q7r8s9t0u"
}
```

| Code              | HTTP Status | Meaning                                    |
| ----------------- | ----------- | ------------------------------------------ |
| `BAD_REQUEST`     | 400         | Malformed request body or query parameters |
| `NONCE_REPLAY`    | 400         | The payment nonce has already been used    |
| `ORG_SUSPENDED`   | 403         | Your organisation has been suspended       |
| `NOT_FOUND`       | 404         | The requested resource does not exist      |
| `ROUTE_NOT_FOUND` | 404         | No active route matched the proxy path     |

## Endpoints Summary

| Method   | Path                           | Auth               | Purpose                      |
| -------- | ------------------------------ | ------------------ | ---------------------------- |
| `GET`    | `/healthz`                     | None               | Liveness probe               |
| `GET`    | `/gateway/:orgSlug/:routePath` | x402 (`X-PAYMENT`) | Paid proxy to upstream       |
| `POST`   | `/api/routes`                  | Bearer             | Create a payment route       |
| `GET`    | `/api/routes`                  | Bearer             | List org routes              |
| `PATCH`  | `/api/routes/:id`              | Bearer             | Update a route               |
| `DELETE` | `/api/routes/:id`              | Bearer             | Delete a route               |
| `GET`    | `/api/gateway/metrics`         | Bearer             | Usage and facilitator health |
| `GET`    | `/mcp/sse`                     | Bearer             | MCP over SSE                 |

<Note>
  Paid proxy routes at `/gateway/:orgSlug/*` authenticate via `X-PAYMENT`, not `Authorization: Bearer`. All other API paths under `/api/*` require a Bearer token.
</Note>

## Explore the API

<CardGroup cols={3}>
  <Card title="Routes" icon="route" href="/api-reference/gateway-routes">
    Create, update, and delete payment routes for your organisation.
  </Card>

  <Card title="Payments" icon="credit-card" href="/api-reference/gateway-payments">
    Understand the x402 two-step flow and proxy endpoint behaviour.
  </Card>

  <Card title="Metrics" icon="chart-bar" href="/api-reference/gateway-metrics">
    Query usage statistics and facilitator health for your gateway.
  </Card>
</CardGroup>