Authentication

The Grid issues two types of API keys. Each key authenticates against a different API and uses a different scheme. This page covers how to generate, use, and rotate both.

Two key types

Key type

API used

Auth scheme

What it covers

Consumption key

Consumption API

Bearer header or x-api-key header

Inference only. Chat completions on the OpenAI-compatible host, messages on the Anthropic Messages host.

Trading key

Trading API

Ed25519-signed requests

Everything beyond inference: instrument specifications, market data, balances, past trades, transfers, and order placement.

If you only consume inference and let Auto Mode buy on your behalf, a Consumption key is enough. The moment you want to read your account balance, fetch instrument specifications programmatically, list past purchases, or place orders yourself, you need a Trading key. Trading keys cover the entire Trading API surface, not just order placement.

Both key types are generated in the dashboard at app.thegrid.ai/profile/api-keys.

Consumption keys

A standard Bearer token. The same key value works on both the OpenAI-compatible host and the Anthropic Messages host. Only the header name changes.

Generate a Consumption key

Sign in at app.thegrid.ai.
Open Profile > API Keys.
Click Create new key, name it something you recognize later (one key per project is a sensible default), and copy the value. The full key is shown once.

Use a Consumption key

On the OpenAI-compatible host (https://api.thegrid.ai/v1), pass the standard Bearer header:

curl -L https://api.thegrid.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Text-Prime", "messages": [{"role": "user", "content": "Hello"}]}'

On the Anthropic Messages host (https://messages-beta.api.thegrid.ai/v1), pass the Anthropic-style header instead. Same key value, different header name:

x-api-key: YOUR_API_KEY

Trading keys

The Trading API uses Ed25519 signature authentication. Every request is signed with your private key, and we verify it against the public key you registered in the dashboard.

Generate an Ed25519 keypair

Generate the keypair locally using a public Ed25519 library. The private key never leaves your machine; only the public key gets registered with us.

Uses the cryptography library (pip install cryptography):

python -c "
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
import base64
sk = Ed25519PrivateKey.generate()
print('private:', base64.b64encode(sk.private_bytes_raw()).decode())
print('public:', base64.b64encode(sk.public_key().public_bytes_raw()).decode())
"

Uses tweetnacl (npm install tweetnacl):

node -e "
const nacl = require('tweetnacl');
const kp = nacl.sign.keyPair();
console.log('private:', Buffer.from(kp.secretKey).toString('base64'));
console.log('public:', Buffer.from(kp.publicKey).toString('base64'));
"

Uses the standard library crypto/ed25519 (no external dependencies):

cat <<'EOF' > genkey.go
package main

import (
    "crypto/ed25519"
    "crypto/rand"
    "encoding/base64"
    "fmt"
)

func main() {
    pub, priv, _ := ed25519.GenerateKey(rand.Reader)
    fmt.Println("private:", base64.StdEncoding.EncodeToString(priv))
    fmt.Println("public:", base64.StdEncoding.EncodeToString(pub))
}
EOF
go run genkey.go

Save the private key in a secrets manager. Treat it like a database credential.

Register the public key

In the dashboard at app.thegrid.ai/profile/api-keys, open the Trading keys section and paste the public key value. The dashboard returns the fingerprint (SHA256 of the public key, base64-encoded without padding); you'll send that fingerprint on every signed request.

Sign a request

The string you sign is the concatenation of:

Unix timestamp in seconds, as a string
HTTP method, uppercase (POST, GET, DELETE)
Request path including any query string (e.g., /v1/orders?status=open)
Request body as a string, or the empty string for GET and DELETE

Sign that string with your Ed25519 private key, then base64-encode the resulting signature. Send three headers on every Trading API request:

Header

Value

x-thegrid-signature

Base64-encoded Ed25519 signature of <timestamp><METHOD><path><body>.

x-thegrid-timestamp

Unix timestamp in seconds, as a string. Must be within 30 seconds of server time, otherwise the request is rejected with 401.

x-thegrid-fingerprint

SHA256 hash of your public key, base64-encoded without padding. The dashboard shows this value when you register the key.

If you see 401 on otherwise-correct requests, check your machine's clock first. Timestamp drift is the most common cause.

Key management

Keep keys out of your source tree. Use environment variables for Consumption keys, and a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, your CI/CD secret store) for Trading private keys.

export GRID_API_KEY="..."

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.thegrid.ai/v1",
    api_key=os.environ["GRID_API_KEY"],
)

Rotation

Rotate keys periodically and any time you suspect exposure:

Generate a new key in the dashboard.
Roll your application to use the new key.
Delete the old key from the dashboard.

The dashboard supports multiple active keys per account, so you can roll without downtime.

Compromised keys

Delete a compromised key in the dashboard immediately. It stops working at the API edge as soon as the deletion propagates. If you suspect billing impact, contact support@thegrid.ai with the key fingerprint and approximate compromise window.

Where next

Consumption API: endpoints that take Consumption keys
Trading API: endpoints that take Trading keys
Errors and rate limits: what 401 looks like and how to debug it

PreviousOverview NextConsumption API

Last updated 17 days ago

Was this helpful?

Good evening

hashtagTwo key types

hashtagConsumption keys

hashtagGenerate a Consumption key

hashtagUse a Consumption key

hashtagTrading keys

hashtagGenerate an Ed25519 keypair

hashtagRegister the public key

hashtagSign a request

hashtagKey management

hashtagRotation

hashtagCompromised keys

hashtagWhere next