Build
API reference
The Mason API follows the OpenAI Chat Completions format. Existing clients work by changing the base URL and key.
Authentication
Send your key as a bearer token: Authorization: Bearer mason_.... Without a key, /v1/chat/completions uses the free daily allowance (30 credits per visitor per day, paid by the treasury).
POST /v1/chat/completions
| Field | Type | Notes |
|---|---|---|
model | string | Required. An id from GET /v1/models. |
messages | array | Required. { role, content } with roles system, user, assistant. |
stream | boolean | Server-sent events in the OpenAI chunk format, ending with data: [DONE]. Default false. |
max_tokens | integer | 1 to 4096, default 1024. Enforced by the orchestrator: a worker that streams past it is cut off. |
temperature | number | 0 to 2. Default 0.7. |
top_p | number | 0 to 1. Default 1. |
stop | string or array | Up to 4 stop sequences. |
The response carries usage (tokens and credits charged) and a mason extension: the anonymous id of the worker that served the job, its runtime and its speed. Standard clients ignore it. Streaming responses also send an X-Mason-Worker header and put usage in the last chunk.
GET /v1/models
Lists the models with at least one trusted worker online right now.
{ "object": "list", "data": [
{ "id": "qwen2.5-1.5b-instruct", "object": "model", "owned_by": "mason", "class": "small", "workers": 1, "credits_per_1k_tokens": 0.2 }
] }Other endpoints
| Endpoint | What it does |
|---|---|
POST /v1/keys | Creates an account and a key (shown once). Five per address per day. |
GET /v1/account | Your credits, usage, and the treasury address for deposits. Needs the key. |
POST /v1/account/deposit | { "tx" }: the hash of an ETH transfer to the treasury whose data is the text mason:<account id>. Credits its dollar value at the on-chain ETH price, once. |
GET /v1/catalog | Every model the network knows, with its browser and Ollama builds and live worker count. |
GET /v1/network | Live network numbers, as shown on the Network page. |
GET /v1/earnings/:wallet | A payout wallet's workers, and its unpaid, earned and paid amounts in dollars. |
POST /v1/stakers/register | { wallet, signature } of the message Mason staking: register <wallet>. |
GET /v1/stakers/:wallet | Registration, counted stake, unpaid and earned amounts in dollars. |
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed body or unknown field value. |
| 401 | invalid_key | Missing, wrong or revoked key. |
| 402 | insufficient_credits | Not enough credits for the request's maximum cost. |
| 402 | free_allowance_used | No key, and today's free allowance is used up. |
| 404 | model_not_found | No such model id. |
| 429 | rate_limited | Too many keys created from this address today. |
| 502 | worker_lost | Sent inside a stream: the worker dropped mid-answer. You were not charged. |
| 503 | no_worker | No worker for this model right now, or none became free within 30 seconds. |