---
title: "Onboard an agent"
description: "Give an agent a key, a base URL and a model. It sends its first request in minutes."
canonical_url: "https://minirouter.sh/docs/guides/agent-onboarding"
markdown_url: "https://minirouter.sh/docs/guides/agent-onboarding.md"
last_updated: "2026-09-26"
---

# Onboard an agent

Give an agent a key, a base URL and a model. It sends its first request in minutes.

[Get a key](https://minirouter.sh/key)

Any agent that speaks the OpenAI or Anthropic API works. Point it at `https://api.minirouter.sh/v1` and give it its own key. Agents that read setup files can fetch [`/agents.md`](https://minirouter.sh/agents.md).

## Quick start

### 1. Get a key

**You**

[Create a key](https://minirouter.sh/key), save the key and dashboard link, then [add credits](https://minirouter.sh/dashboard/billing). Already have an account? Create a key per agent in [Keys](https://minirouter.sh/dashboard/keys).

**The agent**

An agent with a Solana wallet can sign up and fund itself. See [Agent payments](https://minirouter.sh/docs/agent-payments).

### 2. Set the environment

Put the key where the agent runs. Most agents read the OpenAI variables.

```sh
MINIROUTER_KEY=mr-live-YOUR-KEY-HERE
OPENAI_BASE_URL=https://api.minirouter.sh/v1
OPENAI_API_KEY=mr-live-YOUR-KEY-HERE
```

> **Warning:** The base URL ends in `/v1`. Never append `/chat/completions`; the client adds it.

### 3. Pick a model

Use an exact `author/name` ID from the [catalog](https://minirouter.sh/models), or let [`minirouter/auto`](https://minirouter.sh/docs/auto-router) choose. The list is public.

```sh
curl https://api.minirouter.sh/v1/models
```

### 4. Send a first request

```sh
curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-5.6-luna",
  "messages": [
    {
      "role": "user",
      "content": "Reply with: ready"
    }
  ],
  "max_tokens": 64
}'
```

A 200 with `ready` means the agent is connected. The request appears in [Request logs](https://minirouter.sh/dashboard/activity).

## Working example

Send one request and print the reply, the model that answered, its cost and your balance.

**Python**

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minirouter.sh/v1",
    api_key=os.environ["MINIROUTER_KEY"],
)

raw = client.chat.completions.with_raw_response.create(
    model="openai/gpt-5.6-luna",
    messages=[{"role": "user", "content": "Reply with: ready"}],
    max_tokens=64,
)
completion = raw.parse()
print(completion.choices[0].message.content)
print("model:", raw.headers["x-minirouter-model"])
print("cost USD:", raw.headers["x-minirouter-cost-usd"])
print("balance USD:", raw.headers["x-minirouter-balance-usd"])
```

Needs `pip install openai`.

**TypeScript**

```ts
const key = process.env.MINIROUTER_KEY;
if (!key) throw new Error("Set MINIROUTER_KEY");

const res = await fetch("https://api.minirouter.sh/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/gpt-5.6-luna",
    messages: [{ role: "user", content: "Reply with: ready" }],
    max_tokens: 64,
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);

console.log(body.choices[0].message.content);
console.log("model:", res.headers.get("x-minirouter-model"));
console.log("cost USD:", res.headers.get("x-minirouter-cost-usd"));
console.log("balance USD:", res.headers.get("x-minirouter-balance-usd"));
```

No dependencies. Run with Node.js 20 or later as an `.mjs` file.

**cURL**

```sh
curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-5.6-luna",
  "messages": [
    {
      "role": "user",
      "content": "Reply with: ready"
    }
  ],
  "max_tokens": 64
}'
```

Using a coding agent? Its exact settings are in [Integrations](https://minirouter.sh/integrations).

## Keep the key safe

- [One key per agent](https://minirouter.sh/dashboard/keys): Revoke one agent without breaking the rest.
- **Environment only**: Never in prompts, code, logs or repositories.
- [Set an expiry](https://minirouter.sh/docs/authentication): 7, 30 or 90 days, or an exact date.
- [Rotate on exposure](https://minirouter.sh/docs/authentication): The old key works for 24 hours, then stops.

> **Warning:** A leaked key spends your balance. Revoke it in Keys immediately, then create a new one.

## Usage and billing controls

Set limits on each key before an agent runs unattended.

| Control | Effect |
| --- | --- |
| `dailyLimitNano` | Daily spend cap. Over it returns 403 `spend_limit_exceeded`. |
| `monthlyLimitNano` | Monthly spend cap. |
| `rpmLimit` | Requests per minute. |
| `tpmLimit` | Tokens per minute. |
| `allowedModels` | Models this key may call. |

Edit them in [Keys](https://minirouter.sh/dashboard/keys). For budgets and model or provider rules across keys, assign a [guardrail](https://minirouter.sh/docs/guardrails). See [rate limits](https://minirouter.sh/docs/rate-limits).

| Header | Value |
| --- | --- |
| `x-minirouter-cost-usd` | Charge for this request. Streams report `usage.cost` in the final chunk. |
| `x-minirouter-balance-usd` | Remaining balance. |
| `x-minirouter-model` | Model that answered. |
| `x-minirouter-request-id` | Quote this to support. |

> **Tip:** Track spend per key in [Usage](https://minirouter.sh/dashboard/usage). Pricing is in [billing](https://minirouter.sh/docs/billing).

## Troubleshooting

### 401 invalid_api_key

The key is wrong, revoked or expired. Check for spaces or quotes around it, and that it starts with `mr-live-`.

### 402 insufficient_credits

The balance is below the request's estimated cost. [Add credits](https://minirouter.sh/dashboard/billing) or lower `max_tokens`.

### 403 spend_limit_exceeded

The key hit its spend cap. Wait for the reset in the error, or raise the cap in Keys.

### 404 unknown_model

Use the full ID: `openai/gpt-5.6-luna`, not `gpt-5.6-luna`. Fetch the model list for exact IDs.

### 400 No endpoint at …

The base URL is wrong. Use `https://api.minirouter.sh/v1` exactly, without `/chat/completions`.

### 429 usage_limit_exceeded

Wait the seconds in `Retry-After`, or raise the key's request or token limit.

### Free model refused

Accounts created by an agent cannot use [Auto Free](https://minirouter.sh/docs/free-inference). Use a paid model.

Every error carries `error.code` and a link to its fix. Full list: [errors](https://minirouter.sh/docs/errors).