API reference

Quickstart

Get a key on the purchase page (or through the API), then send your first request. The free model (free) works without a key, so you can test before paying.

curl https://shade-gateway.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $SHADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Explain Solana in one sentence."}]
  }'

Tools built on the OpenAI API, such as LangChain, LlamaIndex, the Vercel AI SDK and most agent frameworks, work the same way: set the base URL to https://shade-gateway.vercel.app/v1 and the API key to your SHADE key.

Authentication

Every paid request needs a SHADE key, a secret that starts with shade_sk_. The key is the account: it holds the credit balance and is the only thing that identifies you. Send it as a bearer token:

Authorization: Bearer shade_sk_your_key_here

• We store only a one-way hash of each key, so a lost key can't be recovered. Keep it in a password manager or secret store.
• Anyone with the key can spend its credits. Never ship it in front-end code or commit it to a repository.
• Use separate keys for separate apps or agents. Each one has its own balance and limits.

Models

Pass the id in the model field. Prices are in credits per million tokens (1,000 credits = $1) and follow the providers' current rates. Requests are routed only to providers that don't store or train on prompts, except the free model.

Returns the live list in the OpenAI format, with SHADE pricing. No key needed.

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "owned_by": "openai",
      "name": "GPT-4o mini",
      "free": false,
      "reasoning": false,
      "pricing": { "input_credits_per_m": 225, "output_credits_per_m": 900 }
    }
  ]
}

Chat completions

Generates a reply to a conversation. Request and response bodies follow the OpenAI chat completions format.

Request body

Response

The standard OpenAI response, plus a shade object with the exact credits charged and the remaining balance.

{
  "id": "gen-1762167420-x8Kq2",
  "object": "chat.completion",
  "created": 1762167420,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Solana is a high-speed blockchain..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 31, "total_tokens": 45 },
  "shade": { "charged_credits": 0.03, "balance_credits": 4987.12, "free": false }
}

Streaming

Set "stream": true to receive the reply token by token as Server-Sent Events, in the same chunk format as OpenAI. The last chunk before [DONE] has an empty choices array, the token usage and the shade billing summary. If you disconnect early, generation stops and you pay only for what was produced.

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a haiku about privacy."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Balance

Returns the balance of the key in the Authorization header.

curl https://shade-gateway.vercel.app/api/account -H "Authorization: Bearer $SHADE_KEY"

Funding with SOL

Keys can be created and topped up without a browser, so an agent with a Solana wallet can pay for its own inference. Each top-up gets a unique SOL amount and a Solana Pay reference, priced at the live SOL/USD rate and valid for 30 minutes. The transfer is detected on-chain and credited automatically, usually within seconds of confirmation.

1. Create a key

{ "key": "shade_sk_…", "key_prefix": "shade_sk_ab12", "balance_credits": 0 }

The full key is returned only once. Store it before doing anything else.

2. Start a top-up

Body: { "package_id": "…" }. Available packages:

curl -X POST https://shade-gateway.vercel.app/api/deposits \
  -H "Authorization: Bearer $SHADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"package_id": "starter"}'

3. Send SOL

Send exactly amount_sol to address on Solana mainnet, ideally with reference attached as a read-only account key (Solana Pay). Wallets that open solana_pay_url do this for you.

4. Confirm

Poll every few seconds. status becomes credited and balance_credits shows the new balance. If a manual transfer isn't picked up, POST /api/deposits/{id} with { "signature": "<tx signature>" } to claim it. One transaction can credit only one top-up.

Billing

• 1,000 credits = $1. Credits never expire and there are no subscriptions or minimums.
• Before each request, the maximum it could cost is held from the balance. When it finishes, the exact cost reported by the provider is charged and the rest is released.
• Requests that fail are not charged. A balance can never go below zero.
• Reasoning models count their internal thinking as output tokens, so they cost more per answer.
• Every response tells you what it cost in shade.charged_credits.

Errors

Errors use standard HTTP status codes and a consistent body:

{
  "error": {
    "message": "Not enough credits for this request. Top up on the purchase page.",
    "code": "insufficient_credits",
    "required_credits": 9.41,
    "balance_credits": 2.03
  }
}

Limits

Privacy

• Prompts and responses pass through the gateway in memory and are never written to a database or log.
• We store a hash of each key, token counts and cost per request, and deposit transactions, which is what billing needs.
• IP addresses are hashed with a daily salt for rate limiting and never stored.
• Paid requests are routed only to providers that don't retain or train on prompts. The model provider still processes the prompt to answer it.
• The free model runs on community endpoints that may log prompts. Don't send anything sensitive to it.