Documentation v1 · UPDATED 21 AUG 2026
Search the docs⌘K
Get an API key
On this page
01 — Create a key 02 — Point your client at Spot 03 — Set what you'll pay 04 — Read the fill

Quickstart

Spot implements the OpenAI Chat Completions API. If you already call a hosted model, you are two lines away from buying the same capability at the market price. This page takes about five minutes end to end.

Which client: Clients — OpenAI drop-in on this page, official SDK, aispot CLI, or HTTP. Prompt for an agent: Prompt your agent.

Paths:

01 — Create a key

Keys live in Trade under Developers → API keys. A key is scoped to one environment and carries an optional account-wide price ceiling, which nothing can override at request time.

export SPOT_API_KEY="sk_live_9f2c…"

02 — Point your client at Spot

Keep your SDK, your version, and your request shape. Only the base URL changes.

from openai import OpenAI

client = OpenAI(
    base_url="https://aispotmarket.com/buy/api/v1",
    api_key=os.environ["SPOT_API_KEY"],
)

Discovery for a local or staging gateway:

  1. Pass an explicit base_url / baseUrl to the client constructor, or
  2. Call from_config / fromConfig with a config origin (GET {config_url}/v1/config → gatewayApiUrl), or
  3. Error — there is no hardcoded fallback URL.

Set GATEWAY_URL (explicit constructor) or GATEWAY_CONFIG_URL (discovery) in the environment.

03 — Set what you'll pay

max_price is a hard ceiling in dollars per million tokens, applied to the blended input and output rate. Omit it and the request fills at the prevailing mid.

resp = client.chat.completions.create(
    model="gpt-class-mid",
    max_price=0.28,
    messages=[{"role":"user","content":"ping"}],
)

On the live gateway the field is a decimal string per 1,000 tokens — see Buyer flow and POST /v1/chat/completions.

04 — Read the fill

Every response carries a spot object: what you paid, what list would have been, and which venue class served you. Log it and you have a running record of your own effective rate.

print(resp.spot.fill_price)  # 0.2410
print(resp.spot.vs_list)     # -0.427

Tighten your ceiling with Price limits & routing, or see every field in the Chat completions reference.