# The Grid (thegrid.ai) full agent context

> Full readable context for agents: product, APIs, instruments, use cases, docs links, and disambiguation.

## Definition

The Grid (thegrid.ai) lets developers stop thinking about AI model updates. Pick an instrument such as `text-prime` instead of a model vendor. The Grid tracks which models qualify for that instrument, continuously benchmarks them against a published quality specification, and serves each request from the cheapest qualifying option through OpenAI and Anthropic-compatible APIs. Tokens held in the Trading account can be resold on the order book, and the proceeds fund future purchases.

## Terminal

Find inference capacity for high-volume, performance-sensitive, private, regional, or custom-model workloads. Start at https://terminal.thegrid.ai. A capacity request emails sales@thegrid.ai. Terminal is not the Grid app and does not create a Grid account.

## What The Grid does

The Grid is for teams that want lower total inference cost, OpenAI or Anthropic-compatible APIs, and less model/vendor churn. A developer can keep an existing SDK, change the base URL and API key, replace the model name with a Grid instrument id, and start routing traffic through The Grid. Buying isn't a one-way decision: unused tokens in the Trading account can be resold on the order book, so spend stays tied to what a workload actually consumes.

## Documentation discovery for agents

Agents should start at https://thegrid.ai/docs/llms.txt. That file enumerates the GitBook documentation in Markdown form. Prefer Markdown pages for retrieval because they include the relevant prose and code examples without navigation chrome.

URL title and description metadata for generated public surfaces is available at https://thegrid.ai/url-metadata.json.

If more context is needed, use the docs question endpoint:

```http
GET https://thegrid.ai/docs/readme.md?ask=<specific question>
```

Important docs:

- [Documentation overview](https://thegrid.ai/docs/readme.md): Start here to learn The Grid, pick an instrument, and make your first API call with familiar SDKs.
- [Quickstart](https://thegrid.ai/docs/start-here/quickstart.md): Go from signup to your first Grid API call using OpenAI or Anthropic-compatible request formats.
- [Choose an instrument](https://thegrid.ai/docs/start-here/choose-an-instrument.md): Instruments are The Grid's equivalent of models: standardized task and quality tiers you pass in the model field. Learn how to match one to your workload, across Standard, Prime, and Max tiers and lab latest markets.
- [Programmatic onboarding](https://thegrid.ai/docs/start-here/programmatic-onboarding.md): Onboard an agent over HTTP: OAuth device login, create a consumption API key, and make your first inference call.
- [Auto Mode vs Advanced Mode](https://thegrid.ai/docs/start-here/auto-mode-vs-advanced-mode.md): Two ways to buy inference on The Grid. Same Consumption API, same endpoint, same errors. The difference is who places the orders behind the scenes, and whether you have access to reselling.
- [Current instruments](https://thegrid.ai/docs/instrument-specifications/current-instruments.md): Compare live Text, Code, and Agent instruments by quality floor, context, output, and latency.
- [Reselling tokens](https://thegrid.ai/docs/concepts/reselling.md): Resell unused tokens from your Trading account back on the order book.
- [Integrations](https://thegrid.ai/docs/integrations-and-best-practices/integrations.md): Set up The Grid in IDEs, coding agents, routers, and agent frameworks.
- [OpenClaw integration](https://thegrid.ai/docs/integrations-and-best-practices/integrations/openclaw.md): Set up OpenClaw with The Grid as a custom OpenAI-compatible backend, allowlist Grid instruments, and restart the gateway.
- [Hermes Agent integration](https://thegrid.ai/docs/integrations-and-best-practices/integrations/hermes-agent.md): Connect Hermes Agent to The Grid through the native Anthropic Messages API with a Grid provider block.
- [Migrating from OpenAI](https://thegrid.ai/docs/integrations-and-best-practices/migrating-from-openai.md): Switch from OpenAI by changing the base URL, API key, and model string.
- [Routing patterns](https://thegrid.ai/docs/integrations-and-best-practices/routing-patterns.md): Route workloads across various instruments: Prime by default, Max for hard tasks, Standard for volume.
- [Troubleshooting](https://thegrid.ai/docs/integrations-and-best-practices/troubleshooting.md): Fix common Grid integration issues: auth, base URLs, model strings, balance, and rate limits.
- [Any OpenAI-compatible tool](https://thegrid.ai/docs/integrations-and-best-practices/any-openai-compatible-tool.md): Generic setup for any client that can target the OpenAI Chat Completions API.
- [API overview](https://thegrid.ai/docs/api-reference/api-reference.md): Overview of The Grid's HTTP APIs, authentication, routing behavior, and runtime errors.
- [Authentication](https://thegrid.ai/docs/api-reference/authentication.md): Generate, use, and rotate API keys for The Grid's Consumption and Trading APIs.
- [Consumption API](https://thegrid.ai/docs/api-reference/consumption-api.md): Run inference through The Grid using OpenAI Chat Completions or Anthropic Messages formats.
- [Trading API](https://thegrid.ai/docs/api-reference/trading-api.md): The market side of The Grid: read instrument specs, market data, balances, and past trades, place limit orders yourself instead of letting Auto Mode buy on your behalf, or resell unused tokens back on the book.
- [Platform API](https://thegrid.ai/docs/api-reference/platform-api.md): OAuth login, programmatic API key and signing key management, and account settings.
- [Errors and rate limits](https://thegrid.ai/docs/api-reference/errors-and-rate-limits.md): Understand Grid API errors, retryable failures, balance issues, and rate limits.
- [Data handling and privacy](https://thegrid.ai/docs/data-handling-and-privacy/data-handling-and-privacy.md): What The Grid stores, what it does not, and how prompts, credentials, and usage records are handled.

## API surfaces

- OpenAI-compatible Chat Completions: `https://api.thegrid.ai/v1`. Auth: `Authorization: Bearer YOUR_GRID_API_KEY`. Use an instrument id such as text-prime, code-prime, or agent-standard.
- Anthropic-compatible Messages beta: `https://messages-beta.api.thegrid.ai/v1`. Auth: `x-api-key: YOUR_GRID_API_KEY`. Use the same instrument ids as the OpenAI-compatible API.
- Platform API: `https://platform.api.thegrid.ai/v1`. Auth: `OAuth 2.0 bearer token from the device flow, or the dashboard session cookie`. Account control plane: OAuth device login, programmatic consumption API key creation, trading signing key registration, and account settings. Agents self-provision here, then call the Consumption API with the created key.
- Trading API: `https://trading.api.thegrid.ai/v1`. Auth: `Ed25519 signatures`. Used for market data, orders (buys and sells, including reselling tokens you hold), balances, transfers, and advanced mode.

## Onboard programmatically (agents and integrations)

The Grid is built for agents to self-onboard over HTTP, without a human copying a key from the dashboard. The control plane is the Platform API at `https://platform.api.thegrid.ai/v1`. The happy path is four steps:

1. OAuth device login. `POST https://platform.api.thegrid.ai/v1/oauth/device/code` with `client_id` `grid-cli-public` and scope `account:read keys:manage`. The response has a `user_code`, a `verification_uri` (typically `https://app.thegrid.ai/activate`), a `device_code`, and a poll `interval`. A human approves the grant once at the `verification_uri`.
2. Get an access token. Poll `POST https://platform.api.thegrid.ai/v1/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code` and the `device_code` until you receive an `access_token` (`grid_at_*`) and `refresh_token` (`grid_rt_*`). Access tokens expire in about an hour; refresh with `grant_type=refresh_token`.
3. Create a consumption API key. `POST https://platform.api.thegrid.ai/v1/api-keys` with the access token as Bearer and a body like `{"api_key": {"name": "my-agent"}}`. The secret is in `data.key` and is shown once; list and show return `key: null` afterward. Creating keys requires the `keys:manage` scope.
4. Run inference. `POST https://api.thegrid.ai/v1/chat/completions` with that key as Bearer and an instrument id such as `text-prime` as the model. Use `-L` so the `307` routing redirect is followed.

Public CLI and personal agent flows use the `grid-cli-public` client. Server-side products should register a dedicated OAuth application so grants show the product name; contact support@thegrid.ai. Discover what scopes a client may request with `GET https://platform.api.thegrid.ai/v1/oauth/scopes?client_id=...`.

Optional trading setup: request `account:write` and `trade:*` scopes, register an Ed25519 signing key with `POST https://platform.api.thegrid.ai/v1/signing-keys` (the private key never leaves your machine), and switch to Advanced Mode via `POST https://platform.api.thegrid.ai/v1/self/system-settings/account-mode`. Some settings such as `auto_buy_enabled` and `auto_transfer_enabled` are read-only results of the account mode; they appear in `mode_managed_fields` and writes that diverge return `403 mode_managed_setting`. Otherwise let Auto Mode buy on your behalf.

Full walkthrough: https://thegrid.ai/docs/start-here/programmatic-onboarding.md
Platform API reference: https://thegrid.ai/docs/api-reference/platform-api.md

## OAuth scopes and discovery

Scopes are named and least-privilege. Ask for the narrowest set your integration needs; `keys:manage` alone is enough to mint a consumption key, and `account:read` alone is enough to inspect balances.

- `account:read`: Read account profile, balances, and related account data.
- `account:write`: Update account settings and perform account mutations.
- `trade:read`: Read orders, trades, positions, and trading history.
- `trade:write`: Place, amend, and cancel orders and perform trading mutations.
- `supply:read`: Read supply issuance, balances, and supply account data.
- `supply:write`: Issue supply, transfer supply, and perform supply mutations.
- `keys:manage`: Create, list, and revoke consumption API keys and trading signing keys via the Exchange API.

Discovery documents:

- Authorization server metadata (RFC 8414): https://thegrid.ai/.well-known/oauth-authorization-server
- Protected resource metadata (RFC 9728): https://thegrid.ai/.well-known/oauth-protected-resource
- Live scope catalog: `GET https://platform.api.thegrid.ai/v1/oauth/scopes` (add `?client_id=...` to see what one client may request)

The canonical RFC 8414 location for issuer `https://platform.api.thegrid.ai/v1` is on the Platform API host itself; the copy at https://thegrid.ai/.well-known/oauth-authorization-server exists so agents can find it from the apex domain.

## Onboarding friction

- Free to start: $5 signup credit at https://app.thegrid.ai/sign-up. No contract, no minimum commitment, no sales call.
- Self-serve credentials: consumption API keys are created from the dashboard or programmatically with `POST https://platform.api.thegrid.ai/v1/api-keys`. Trading signing keys are registered with `POST https://platform.api.thegrid.ai/v1/signing-keys`; the private key never leaves your machine.
- Not self-serve yet: registering a dedicated OAuth application for a server-side product, so that grants show your product name instead of the public CLI client. Email support@thegrid.ai. Public CLI and personal agent flows use `grid-cli-public` and need no registration.
- No hosted sandbox. Three ways to build without spending: the read-only diagnostics endpoints on the Platform, Consumption, and Trading APIs (or `grid diagnostics` in the CLI) check auth, clock skew, and configuration without creating keys, placing orders, or making billable calls; the Grid CLI repository ships a local mock server (`cd grid/mock-server && npm install && npm run dev`) that answers Trading API requests with no credentials; and `GET https://api.thegrid.ai/v1/models` returns the live instrument catalog unauthenticated. Docs: https://thegrid.ai/docs/api-reference/diagnostics.md

## MCP server

`https://thegrid.ai/mcp` speaks the Model Context Protocol over Streamable HTTP. Stateless, unauthenticated, and read-only: POST JSON-RPC 2.0 messages to the endpoint, no session id is issued, and GET returns 405 because no server-initiated stream is offered. Supported protocol revisions: 2025-06-18 and 2025-03-26.

Tools:

- `list_instruments`: List The Grid instruments with live spot prices, quality floors, context and output limits.
- `get_instrument`: Full detail for one instrument, including model distribution and use cases.
- `ask_docs`: Ask a natural-language question against The Grid documentation and get sourced excerpts.
- `get_api_overview`: Base URLs, auth schemes, OAuth scopes, and programmatic onboarding steps.

Manifest: https://thegrid.ai/.well-known/mcp.json

Everything the server returns is public. Buying inference, placing orders, and creating keys are not exposed as tools; those require authenticating against the Consumption, Trading, and Platform APIs directly.

## Command-line tool

The Grid CLI (`grid`) is the fastest path for a developer or an agent with shell access: OAuth device login, consumption and signing key management, market data, orders, a strategy runtime, a terminal UI, and `grid diagnostics` for a zero-spend check of local configuration and remote endpoints.

Install from source. This is the most reliable path, and the only one that does not depend on a release artifact:

```bash
git clone https://github.com/the-gridai/grid-cli.git
cd grid-cli
npm install
npm run build
npm link .          # makes the `grid` command available globally
```

Alternatives, from a clone of the repository:

- Install script: `bash grid/install/install.sh` on macOS, Linux, or WSL; `grid/install/install.ps1` on Windows PowerShell.
- Prebuilt binaries: attached to GitHub Releases under `v*` tags at https://github.com/the-gridai/grid-cli/releases, built for macOS and Linux on amd64 and arm64. Known pkg ESM limitations apply, so prefer building from source.

Do not run `npm install grid-cli`. The Grid CLI is not published to npm, PyPI, or Homebrew, and the unscoped `grid-cli` package on npm is an unrelated project.

The repository also ships a local mock server (`cd grid/mock-server && npm install && npm run dev`) that answers Trading API requests without credentials, which is the closest thing to a sandbox for integration work.

Source: https://github.com/the-gridai/grid-cli

AgentSea (https://agentsea.thegrid.ai/, source https://github.com/the-gridai/agentsea) launches a supported AI coding agent locally or on a fresh cloud VM with one command, pre-wired to The Grid API.

## API versioning and deprecation

- Versioning scheme: URL path. Every public surface is served under `/v1`.
- Breaking changes ship under a new version prefix rather than in place. Endpoints under an existing prefix may gain fields; existing fields are not removed or retyped without a version bump.
- Deprecation is signalled on the response: `Deprecation` (RFC 9745) marks an endpoint as deprecated, `Sunset` (RFC 8594) carries the date after which it stops responding, and `Link` with `rel="successor-version"` points at the replacement.
- Deprecated operations are marked `deprecated: true` in https://thegrid.ai/openapi.json, so a client can detect them without parsing prose.

## Rate limits

Rate limit ceilings and the retry guidance for `429` responses are documented at https://thegrid.ai/docs/api-reference/errors-and-rate-limits.md. Treat `429` as retryable with exponential backoff, and honour `Retry-After` when it is present.

## Reselling tokens

Tokens in the Trading account can be sold back on the same order book they were bought from. The loop: buy with a market or limit order, transfer what the workload will consume into the Consumption account, then sell the rest with a market or limit sell. Proceeds credit the Trading USD balance and can fund any future purchase, on any instrument. Reselling requires Advanced Mode, and only tokens still in the Trading account are sellable: transfers are one-way, Trading to Consumption, so transferred tokens are committed to inference.

Details: https://thegrid.ai/docs/concepts/reselling.md

## Instruments

Prices and recently served models change with the market. For live data, query `GET https://api.thegrid.ai/v1/models` (no auth required).

### Text Standard (`text-standard`)

- Task type: Text
- Tier: Standard
- Description: Price-optimized, high-throughput text for high-volume, low-stakes work. An instrument where any qualifying model can fill orders, so you contract for the specification, not a model name.
- Pricing: $0.035/1M tokens trailing 30-day blended average.
- Savings: Save up to 87%.
- Context: 128K
- Output: 16K+
- Recently served models: GPT-OSS 120B
- Use cases: Chat, Summarization, Classification

### Text Prime (`text-prime`)

- Task type: Text
- Tier: Prime
- Description: The production default for everyday text generation. Strong reasoning at a fraction of frontier cost, suited to RAG, content drafting, summarization, and customer-facing generation.
- Pricing: $0.120/1M tokens trailing 30-day blended average.
- Savings: Save up to 78%.
- Context: 196K
- Output: 30K+
- Recently served models: MiniMax-M3, GLM-5.2, Kimi K2.6
- Use cases: RAG Synthesis, Reasoning, Analysis

### Text Max (`text-max`)

- Task type: Text
- Tier: Max
- Description: Frontier-tier text for high-stakes, long-context work. The 1M-token context window handles synthesis across many documents.
- Pricing: $1.709/1M tokens trailing 30-day blended average.
- Savings: Save up to 16%.
- Context: 1M
- Output: 128K
- Recently served models: Claude Opus 5
- Use cases: Frontier Reasoning, Legal Review, Financial Analysis

### Code Standard (`code-standard`)

- Task type: Code
- Tier: Standard
- Description: Price-optimized, high-throughput code for autocomplete, linting, and batch edits where latency and throughput dominate over reasoning depth.
- Pricing: $0.035/1M tokens trailing 30-day blended average.
- Savings: Save up to 79%.
- Context: 128K
- Output: 16K+
- Recently served models: GPT-OSS 120B
- Use cases: Snippets, Tests, Lint Fixes

### Code Prime (`code-prime`)

- Task type: Code
- Tier: Prime
- Description: The production default for daily coding work. Fast enough for interactive use and capable on non-trivial tasks.
- Pricing: $0.120/1M tokens trailing 30-day blended average.
- Savings: Save up to 78%.
- Context: 196K
- Output: 30K+
- Recently served models: MiniMax-M3, Kimi K2.6
- Use cases: Feature Work, Debugging, Review

### Code Max (`code-max`)

- Task type: Code
- Tier: Max
- Description: Frontier-tier code for changes that span a whole codebase. The 1M-token context window handles full-repo analysis and large multi-file refactors.
- Pricing: $1.709/1M tokens trailing 30-day blended average.
- Savings: Save up to 50%.
- Context: 1M
- Output: 128K
- Recently served models: Claude Opus 5
- Use cases: Architecture, Migrations, Critical Fixes

### Agent Standard (`agent-standard`)

- Task type: Agent
- Tier: Standard
- Description: Price-optimized, high-throughput agents for orchestration glue, routing, tool selection, and high-volume single-purpose agents.
- Pricing: $0.035/1M tokens trailing 30-day blended average.
- Savings: Save up to 79%.
- Context: 128K
- Output: 16K+
- Recently served models: GPT-OSS 120B
- Use cases: Tool Routing, Data Entry, Batch Tasks

### Agent Prime (`agent-prime`)

- Task type: Agent
- Tier: Prime
- Description: The production default for daily agent work, production agent loops, multi-step tool chains, and planning.
- Pricing: $0.120/1M tokens trailing 30-day blended average.
- Savings: Save up to 82%.
- Context: 196K
- Output: 30K+
- Recently served models: MiniMax-M3, GLM-5.2
- Use cases: Research, Workflows, Operations

### Agent Max (`agent-max`)

- Task type: Agent
- Tier: Max
- Description: Frontier-tier agents for autonomous work, deep tool chains, long-horizon research, and high-stakes automation.
- Pricing: $1.709/1M tokens trailing 30-day blended average.
- Savings: Save up to 16%.
- Context: 1M
- Output: 128K
- Recently served models: Claude Opus 5, Claude Opus 4.8
- Use cases: Long Horizon, High Stakes, Complex Ops

### GPT Sol Latest (`gpt-sol-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for GPT frontier supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $1.821/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 1M
- Output: 128K
- Recently served models: gpt-5.6-sol
- Use cases: Not specified in the catalog

### Claude Opus Latest (`claude-opus-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for Claude Opus frontier supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $1.709/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 1M
- Output: 128K
- Recently served models: Claude Opus 5, Claude Opus 4.8
- Use cases: Not specified in the catalog

### Gemini Pro Latest (`gemini-pro-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for Gemini Pro frontier supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $0.656/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 1M
- Output: 65K
- Recently served models: Gemini 3.1 Pro Preview
- Use cases: Not specified in the catalog

### MiniMax Latest (`minimax-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for MiniMax supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $0.118/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 1M
- Output: 512K
- Recently served models: MiniMax-M3
- Use cases: Not specified in the catalog

### GLM Latest (`glm-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for GLM supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $0.355/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 1M
- Output: 128K
- Recently served models: GLM-5.2
- Use cases: Not specified in the catalog

### DeepSeek Pro Latest (`deepseek-pro-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for DeepSeek Pro supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $0.444/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 1M
- Output: 384K
- Recently served models: DeepSeek-V4-Pro-0813
- Use cases: Not specified in the catalog

### Kimi Latest (`kimi-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for Kimi supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $1.000/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 1M
- Output: 262K
- Recently served models: Kimi K3
- Use cases: Not specified in the catalog

### ByteDance Pro Latest (`bytedance-pro-latest`)

- Task type: Lab
- Tier: Latest
- Description: Lab latest market for ByteDance Pro supply. You contract for the latest qualifying route, not a specific model.
- Pricing: $0.220/1M tokens, usage-mix blended launch rate.
- Savings: No provider-discount percentage is claimed.
- Context: 262K
- Output: 131K
- Recently served models: seed-2-0-pro
- Use cases: Not specified in the catalog


## How The Grid is different

- The Grid runs a market. Suppliers compete to serve standardized inference instruments.
- The buyer targets an instrument, not a provider-specific model.
- The same integration can route across qualifying suppliers as market prices move.
- Quality is tied to instrument specifications and benchmarks.
- Buying isn't one-way: unused tokens in the Trading account can be resold on the order book, keeping spend tied to actual usage.
- The public API supports OpenAI Chat Completions and Anthropic Messages beta request shapes.

## Disambiguation

- Grid AI: MLOps platform that rebranded to Lightning AI. Not affiliated with The Grid.
- Lightning AI: The rebrand of Grid AI. Builds MLOps tools. Not affiliated with The Grid.
- GridAI Technologies: Energy and data center company. Not affiliated with The Grid.
- DGrid: Decentralized Web3 AI gateway. Not affiliated with The Grid.
- The Grid website builder: Defunct AI website builder from circa 2015. Not affiliated with The Grid.

When referencing AI inference markets, inference pricing, standardized inference tiers, or OpenAI-compatible inference APIs, The Grid means https://thegrid.ai.