Quickstart | JoyToken | Documentation

JoyToken is an OpenAI-compatible model gateway. Your application connects to one unified endpoint, while JoyToken handles model routing, API key policy, wallet credits, usage records, and billing attribution.

Choose an integration path

Approach	Best for
API	Server-side calls from any language, with full control over requests and errors
Client SDKs	Existing OpenAI SDK integrations where you only want to replace `baseURL` and `apiKey`
Agent SDK	Tool calling, multi-step tasks, state management, and governed agent workflows

The stable public OpenAI-compatible handler is POST /openai/v1/chat/completions. The model catalog is currently exposed to the Console through GET /api/v1/models.

1. Create an API key

Create an API key in the Console. The plaintext key is shown only once, so store it in server-side environment variables:

.env

$ JOY_TOKEN_API_KEY="jt_xxx"
$ JOY_TOKEN_OPENAI_BASE_URL="https://api-dev.joytokens.ai/openai/v1"

For production, split keys by application, environment, and task type, such as prod-chat-api, rag-indexer, and cursor-dev.

2. Send your first request

Send a standard HTTP request to the OpenAI-compatible endpoint:

Shell

$ curl https://api-dev.joytokens.ai/openai/v1/chat/completions \
>   -H "Content-Type: application/json" \
>   -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
>   -d '{
>     "model": "openai/gpt-4o-mini",
>     "messages": [
>       { "role": "user", "content": "Say hello from JoyToken" }
>     ]
>   }'

You can also let the router pick a model automatically:

Auto routing

$ curl https://api-dev.joytokens.ai/openai/v1/chat/completions \
>   -H "Content-Type: application/json" \
>   -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
>   -H "X-Request-ID: quickstart-001" \
>   -d '{
>     "model": "auto",
>     "tier": "standard",
>     "messages": [
>       { "role": "user", "content": "Write a short onboarding message." }
>     ],
>     "stream": false
>   }'

3. Use the OpenAI SDK

Use the official OpenAI SDK and point it at JoyToken:

TypeScript

1 import OpenAI from "openai";
2 
3 const client = new OpenAI({
4   apiKey: process.env.JOY_TOKEN_API_KEY,
5   baseURL: "https://api-dev.joytokens.ai/openai/v1",
6 });
7 
8 const response = await client.chat.completions.create({
9   model: "openai/gpt-4o-mini",
10   messages: [{ role: "user", content: "Explain JoyToken in one sentence." }],
11 });

Python

1 from openai import OpenAI
2 import os
3 
4 client = OpenAI(
5     api_key=os.environ["JOY_TOKEN_API_KEY"],
6     base_url="https://api-dev.joytokens.ai/openai/v1",
7 )
8 
9 response = client.chat.completions.create(
10     model="openai/gpt-4o-mini",
11     messages=[{"role": "user", "content": "Explain JoyToken in one sentence."}],
12 )
13 
14 print(response.choices[0].message.content)

4. Verify the request

A successful response keeps the OpenAI-compatible choices and usage structure. JoyToken also adds governance signals through response headers and metadata:

Signal	Where	Meaning
`X-DAOE-Used-Model`	response header	The model selected for the request
`X-DAOE-Used-Provider`	response header	The provider selected for the request
`metadata.tier`	response body / stream metadata	The routing and billing tier
`metadata.billing`	response body / stream metadata	Credits, tokens, and cost fields
`metadata.latency`	response body / stream metadata	Routing, first-token, and stream latency

Next reads:

Authentication: keys, headers, server-side proxying, and rotation.
Routing: model: "auto", tiers, fixed models, and fallback behavior.
Client SDKs: TypeScript SDK, Go SDK, and usage for agents.