> ## 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.

# Routes: Create and Manage Paid Meterlane Endpoints

> Create and manage payment routes: a URL path, a USDC price, and an upstream HTTP target — all scoped to your organization on Meterlane.

A route is the fundamental building block of the Agent Gateway. Each route combines three things: a URL path that agents call, a price in USD that is charged per request, and a target upstream URL that the gateway proxies to after payment is verified. Routes are scoped to your organization — agents reach them at `https://gateway.meterlane.app/gateway/{orgSlug}/{routePath}`. You can create and manage routes either from the Meterlane dashboard or programmatically through the management API.

## What a route contains

| Field            | Type      | Description                                                                                                      |
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `path`           | `string`  | URL path suffix, e.g. `/summarize`. Must start with `/`.                                                         |
| `priceUSD`       | `number`  | Per-request charge in USD, settled as USDC on-chain.                                                             |
| `targetUrl`      | `string`  | Full URL of your upstream HTTP service.                                                                          |
| `network`        | `string`  | Chain to settle on: `eip155:8453` (mainnet) or `eip155:84532` (Sepolia).                                         |
| `active`         | `boolean` | Whether the route accepts paid traffic. Defaults to `true`.                                                      |
| `streaming`      | `boolean` | Set to `true` to pipe upstream SSE responses without buffering.                                                  |
| `discoverable`   | `boolean` | List this route on [x402.org Bazaar](https://x402.org) for agent discovery.                                      |
| `description`    | `string`  | Human-readable description surfaced to agents and in Bazaar listings.                                            |
| `bazaarCategory` | `string`  | Category tag for Bazaar discovery (e.g. `"data"`, `"ai"`, `"finance"`). Only used when `discoverable` is `true`. |

## Creating routes from the dashboard

The dashboard at [meterlane.app/dashboard](https://meterlane.app/dashboard) is the easiest way to create your first route.

<Steps>
  <Step title="Open Routes">
    Navigate to **Dashboard → Routes** and click **New Route**.
  </Step>

  <Step title="Configure the route">
    Fill in the path, price, and your upstream URL. Choose the network that matches your upstream environment — use Base Sepolia for staging and Base mainnet for production.
  </Step>

  <Step title="Save and test">
    Click **Save**. Your route is immediately live. Copy the gateway URL shown in the route detail panel and test it with curl to confirm the `402` challenge appears.
  </Step>
</Steps>

## Management API

Use the management API to create and manage routes programmatically — useful for CI/CD pipelines, infrastructure-as-code, or dynamic route generation.

All management API requests require your organization's API key in the `Authorization` header.

### Create a route

```bash theme={null}
curl -X POST https://gateway.meterlane.app/api/routes \
  -H "Authorization: Bearer bp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/summarize",
    "priceUSD": 0.01,
    "targetUrl": "https://api.yourservice.com/summarize",
    "network": "eip155:8453",
    "description": "Summarize a document with GPT-4o",
    "streaming": false,
    "discoverable": false
  }'
```

A successful response returns `201` with the full route object:

```json theme={null}
{
  "id": "rte_01hx…",
  "path": "/summarize",
  "priceUSD": 0.01,
  "targetUrl": "https://api.yourservice.com/summarize",
  "network": "eip155:8453",
  "active": true,
  "streaming": false,
  "discoverable": false,
  "description": "Summarize a document with GPT-4o"
}
```

### List routes

```bash theme={null}
curl https://gateway.meterlane.app/api/routes \
  -H "Authorization: Bearer bp_live_…"
```

Returns an array of all routes under your organization, ordered by creation date (newest first).

### Update a route

Use `PATCH /api/routes/{id}` to change any field on an existing route. You only need to include the fields you want to update:

```bash theme={null}
curl -X PATCH https://gateway.meterlane.app/api/routes/rte_01hx… \
  -H "Authorization: Bearer bp_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "priceUSD": 0.05, "active": true }'
```

### Disable a route

Set `"active": false` via `PATCH`, or `DELETE /api/routes/{id}` to permanently deactivate it and remove it from Bazaar discovery. Deactivated routes return `404` to agents.

## Route pricing

Every route uses a fixed per-request price denominated in USD and settled in USDC. Set `priceUSD` to any value greater than `0`. The gateway converts your USD price to the equivalent USDC token units at the time of payment configuration — there is no dynamic FX conversion at request time.

<Tip>
  Start with a low price (e.g. `0.001` — one tenth of a cent) while testing. You can update the price at any time via `PATCH` without disrupting existing agent integrations.
</Tip>

## SSE streaming routes

If your upstream returns a Server-Sent Events stream (for example, a streaming LLM response), set `"streaming": true` on the route. The gateway will pipe bytes directly to the agent without buffering the full response body first.

<Note>
  Streaming routes settle payment before opening the upstream connection. The agent pays the full route price upfront, then receives the stream.
</Note>

## Discoverable routes (Bazaar)

Setting `"discoverable": true` on a route lists it in the [x402.org Bazaar](https://x402.org), a public registry where AI agents can discover paid HTTP APIs. Include a clear `description` and optionally a `bazaarCategory` to improve discoverability.

```bash theme={null}
curl -X POST https://gateway.meterlane.app/api/routes \
  -H "Authorization: Bearer bp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/weather",
    "priceUSD": 0.005,
    "targetUrl": "https://api.yourservice.com/weather",
    "network": "eip155:8453",
    "description": "Real-time weather data for any city",
    "discoverable": true,
    "bazaarCategory": "data"
  }'
```

Set `"discoverable": false` or call `DELETE /api/routes/{id}` to remove a listing from Bazaar.

## Sandbox demo route

The public route at `https://gateway.meterlane.app/gateway/demo/demo` is a read-only sandbox maintained by Meterlane. It always responds with a `402` challenge on an unpaid request and accepts test payments on Base Sepolia. Use it to validate your agent's x402 client integration before creating your own routes.

<Warning>
  Do not use the `demo` org slug for production traffic. It is a shared sandbox and does not credit any real wallet.
</Warning>