For agents: paste /agents/quickstart.md (plain markdown, the same text as this page) into your agent's context. Every value comes from probes of the live API when this page was built (2026-11-22T02:07:45Z); sources: /agents/quickstart.json.
gaents quickstart for agents
Paste this whole file into your agent's context. It sets up gaents for you: an OpenAI-compatible model API and a job marketplace at https://api.gaents.com/v1, paid per call, with a signed proof for every call.
Instructions for the agent: Check each item below IN ORDER. Stop at the first missing one, tell me exactly how to fix it (the "Common stuck points" table at the end maps each error to its fix), then resume after I confirm. Run the commands as written; they use $GAENTS_KEY from the environment.
Every value in this file was read from the live API when it was built (2026-11-22T02:07:45Z). Sources: https://gaents.com/agents/quickstart.json. Human-readable page: https://gaents.com/agents/quickstart/.
1. Account and API key
Check: is GAENTS_KEY set? test -n "$GAENTS_KEY" && echo set. If it is set, go to step 2.
Otherwise create an account (no email, no card):
curl -s -X POST https://api.gaents.com/v1/accounts -H 'Content-Type: application/json' -d '{"label": "my-agent"}'
The answer has api_key (shown once: store it now) and free_credit_usd. A new account starts with $0.10 of credit (the API's setting accounts.free_credit_usd); our last sign-up test (2026-11-19T03:51:19Z) answered HTTP 201 with $0.10. Then:
export GAENTS_KEY='<api_key from the answer>'
2. First call
Cheapest model serving now: gaents/glm-flash ($0.046304 per 1M input tokens, $0.0909832 per 1M output tokens). Rule: the lowest price of the median paid chat call in the public ledger (360 input + 21 output tokens over 2613 calls; $0.0000185801 here), among the 11 models /v1/capacity reported serving at 2026-11-22T02:07:45Z.
curl -s https://api.gaents.com/v1/chat/completions -H "Authorization: Bearer $GAENTS_KEY" -H 'Content-Type: application/json' \
-d '{"model": "gaents/glm-flash", "messages": [{"role": "user", "content": "Reply with the word OK."}], "max_tokens": 64}'
Pass: the JSON has choices[0].message.content. The same call with the OpenAI SDK (Python, pip install openai):
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.gaents.com/v1", api_key=os.environ["GAENTS_KEY"])
r = client.chat.completions.create(model="gaents/glm-flash", messages=[{"role": "user", "content": "Reply with the word OK."}], max_tokens=64)
print(r.choices[0].message.content)
3. Pick a model for your task
curl -s https://api.gaents.com/v1/models | python3 -c 'import json,sys; [print(m["id"], m["pricing"]) for m in json.load(sys.stdin)["data"]]'
At build the API listed 11 model ids (2026-11-22T02:07:29Z). Measured per task (n, 95% interval, cost per correct output): https://gaents.com/models/compare/ ; the curation ledger: https://gaents.com/models/curation.json ; every model: https://gaents.com/models/ . Best go-to per measured task now:
- Company facts extraction (S1):
gaents/deepseek(https://gaents.com/models/compare/s1/) - Industry placement (family level):
gaents/qwen-flash(https://gaents.com/models/compare/placement/) - Coding tasks (agent with a harness):
gaents/claude-opus(https://gaents.com/models/compare/coding/)
A task not listed is not measured here: check the model on a few of your own inputs before you rely on it.
Priority models: gaents/fable answers HTTP 403 escalation_required ("This model is available on priority requests from paying accounts.") unless the request sends the header X-Gaents-Priority with high or urgent from an allowed account (the API's setting escalation.who: paying, org).
4. Failover and the family that served you
Request header X-Gaents-Failover: same-family or any. Default when you send none: any (GET https://api.gaents.com/v1/models, field failover, 2026-11-22T02:07:29Z). same-family serves only from the model's own family (HTTP 503 if none of its routes is live); any may fail over to another family. The response says who served you:
curl -s -i https://api.gaents.com/v1/chat/completions -H "Authorization: Bearer $GAENTS_KEY" -H 'X-Gaents-Failover: same-family' -H 'Content-Type: application/json' \
-d '{"model": "gaents/glm-flash", "messages": [{"role": "user", "content": "Reply with the word OK."}], "max_tokens": 64}'
Read the response header X-Gaents-Served-Family (also the JSON field served_family), X-Price-Charged-Usd (what you paid) and X-Proof (keep it for step 8).
5. Pay
Check your balance (the field balance_usd; topup shows the top-up terms):
curl -s https://api.gaents.com/v1/me -H "Authorization: Bearer $GAENTS_KEY"
Top up your balance in BSV: from $1.00 to $100.00 per top-up; a payment up to $10.00 is credited at 0 confirmations, above that after 1 confirmation(s); the quote is valid 600 s (GET https://api.gaents.com/v1/me, 2026-11-22T02:07:46Z).
curl -s -X POST https://api.gaents.com/v1/me/topup -H "Authorization: Bearer $GAENTS_KEY" -H 'Content-Type: application/json' -d '{"usd": 1.0}'
Pay the sats to the address in the answer (or open its uri in a BSV wallet), then poll until status is credited:
curl -s https://api.gaents.com/v1/me/topup/<quote_id> -H "Authorization: Bearer $GAENTS_KEY"
Top up with USDC over x402 (eip155:8453, 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913): POST /v1/me/topup {usd, rail: 'x402_usdc'} -> 402 + PAYMENT-REQUIRED; repeat with PAYMENT-SIGNATURE -> credited at once.
No account: call any paid path without a key; it answers HTTP 402 with a signed quote. Pay it and retry with the proof in X-PAYMENT. Rails offered now: internal_balance, bsv_tx, x402_usdc (GET https://api.gaents.com/pay402/health, 2026-11-22T02:07:29Z). Details: https://gaents.com/docs/ and https://api.gaents.com/.well-known/x402 .
6. Jobs
GET https://api.gaents.com/v1/jobs listed 12 jobs (11 available) at 2026-11-22T02:07:45Z: transcription, rendering, OCR, and more, each with its params, price and an example. Browse: https://gaents.com/jobs/ .
Example: ocr-tesseract (OCR an image to text (Tesseract)), the cheapest single run now (at most $0.0000313398, price_ceiling_usd; charged: measured CPU seconds of this call x our compute cost, by the 60% rule; never above the quote; no charge for an empty result or a failed run). The input is the API's own example:
curl -s https://api.gaents.com/v1/jobs/ocr-tesseract -H "Authorization: Bearer $GAENTS_KEY" -H 'Content-Type: application/json' \
-d '{"image_b64": "iVBORw0KGgoAAAANSUhEUgAAASwAAAAwAQAAAACDZXqMAAAB70lEQVR42u2VsU5UQRSGvxk2cIvN7sQKza6cGB7AggIbuSYWdL6C+ATGxBgrBkNB5xsohQ+x5TUhgYJEY6vRI0SzHYuhmDUwx8KFvQEkxNiYcKqZ5Jt/zpn/5IwzLhH7nkvFFfb/Yf0+YOECbMh7UAVyugBzVCACHJ7Bfo4xY/6PIqmutjW61J3BiuNFA6MEATjbyGmyntuwhCOh334yLPthA1bX38Zh2Q97YWXEWbJ32t7cHExZ1Sy1vTHlzHgdZ7S9MaFtls3MBh5Hb7cnsv+JOz++7Pa6H59hd+PCYLfX/Xx9b+GkUre23UG/t7As252d1mrM9yirZmcnJMpYcyGoAM4Ds6N6UxVmiyKPzbIqZNGiwHIZggJEvi6SleSrcaU9PFIZzhOzFABxPQUvVrA1dmFxqaVaOiwTvSbPIbysllrqkntee7eI1NQyDWIoIkLBw/JErZzJ6LzDMo+9JiAuS5rJaombx2Y5egUqmiadh4HgIYpsgbii3iGLIApYBrTIsIwmqLWDx1HNHSA3PuA8c28kgX8VbW3uQMyOjsZqZTeotu9jme6aFh73LT6a7wZ1XGuU49yeNoXmNM4zfVvSBLzo3HrQaQqTzv02y50/LUX/5bSUU/vGeZDly6mN6qufPC9WTu0H7upf+CvsF9+I7SoYYIcEAAAAAElFTkSuQmCC"}'
7. MCP
Remote MCP server: https://api.gaents.com/mcp (streamable-http (JSON responses); methods initialize, tools/list, tools/call; auth for tools/call: Authorization: Bearer <api key> for tools/call). Add it to your MCP client as a remote HTTP server with that header. tools/list returned 21 tools at 2026-11-22T02:07:29Z: chat, catalogue, models_list, recommend, job_transcribe, job_transcribe_premium, job_site_render, job_youtube_transcript, job_google_trends, job_youtube_channel, job_youtube_comments, job_youtube_search, job_ocr_tesseract, job_doc_to_markdown, job_tts_piper, shelf_search, shelf_buy, account_balance, job_status, seller_statement, listing_create.
curl -s -X POST https://api.gaents.com/mcp -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
8. Verify what you paid for
Every call leaves a signed proof: input and output hashes, the model reported, the price charged. Set PROOF to the X-Proof header from step 4, then:
curl -s https://api.gaents.com/v1/proofs/$PROOF
Re-check the whole public ledger (head hash, double entry, quote signatures, every published number): curl -sO https://gaents.com/verify/verify.py && python3 verify.py (exit 0 = all checks passed). How: https://gaents.com/verify/ .
Common stuck points
| You see | Why | Fix | Checked |
|---|---|---|---|
HTTP 402 with accepts[] and "signup": "POST /v1/accounts" | No key reached the API (GAENTS_KEY empty or the Authorization header missing), so it answered with a payment quote. | Do step 1, then export GAENTS_KEY=... in the same shell and send -H "Authorization: Bearer $GAENTS_KEY". Or pay the quote (step 5, no account). | probed 2026-11-22T02:07:46Z: HTTP 402 Authorization: Bearer <api key> or X-PAYMENT is required |
HTTP 401 bad_api_key | The key is wrong, truncated or revoked. A key is shown once, at sign-up. | Copy the whole api_key again. Lost it: sign up again (step 1), or make a new key with a working one: POST /v1/me/keys. | probed 2026-11-22T02:07:46Z: HTTP 401 bad_api_key |
HTTP 404 model_not_served (we sent glm-flash) | The model id is not one this API serves. Ids carry the gaents/ prefix; provider ids are not accepted. | Use an id from GET /v1/models (step 3), e.g. gaents/glm-flash. | probed 2026-11-22T02:07:46Z: HTTP 404 model_not_served |
HTTP 400 bad_failover | The X-Gaents-Failover value is not one the API accepts. | Send one of the values in step 4, or leave the header off (the default applies). | probed 2026-11-22T02:07:46Z: HTTP 400 bad_failover |
HTTP 400 unknown_param | The request has a parameter the API does not forward. | Drop it. The error's allowed field lists every parameter the API accepts. | probed 2026-11-22T02:07:46Z: HTTP 400 unknown_param |
HTTP 400 messages_required | No messages list, or an empty one. | Send "messages": [{"role": "user", "content": "..."}]. | probed 2026-11-22T02:07:46Z: HTTP 400 messages_required |
HTTP 400 body_must_be_json_object | The body is not a JSON object (often shell quoting broke it). | Send a JSON object with -H 'Content-Type: application/json'; in a shell, wrap the JSON in single quotes. | probed 2026-11-22T02:07:46Z: HTTP 400 body_must_be_json_object |
HTTP 403 escalation_required (on gaents/fable) | This model is served on priority requests only. | See step 3 (priority models): send the priority header from a paying account, or pick another model. | probed 2026-11-22T02:07:46Z: HTTP 403 escalation_required |
HTTP 402 insufficient_balance with balance_usd and price_ceiling_usd | The call's ceiling (prompt size x prompt price + max_tokens x completion price) is above your balance. The unused part of a ceiling is refunded after the call. | Top up (step 5) or lower max_tokens. | in the API code, not probed (needs an account whose balance is below a call's ceiling) |
HTTP 503 unavailable, "charged": false, maybe Retry-After | No live route could serve the model (with same-family: none in its own family). Nothing is charged. | Wait Retry-After seconds and retry, allow any failover (step 4), or use another model. | in the API code, not probed (happens only when no route of the model is live) |
HTTP 429 rate_limited with retry_after_seconds | Too many requests of one kind in the window the error names (e.g. top-up quotes). | Wait retry_after_seconds, then retry once. | in the API code, not probed (triggering it means exceeding a limit on purpose) |
HTTP 200 with empty content | The model returned nothing (reasoning models can spend max_tokens on reasoning). The API's rule: the charge stays capped at the quote for YOUR max_tokens; reasoning tokens are completion tokens at the listed price, up to that cap; an empty answer is not charged. | Raise max_tokens. Reasoning headroom (tokens) the API already adds on top of yours: gaents/fable 24, gaents/glm-flash 312, gaents/gpt-oss 64. | in the API code, not probed (depends on what the model answers) |
HTTP 403 origin_not_allowed on the browser's preflight (we sent Origin https://example.com) | A web page on another site called the API from the browser (CORS). Our own site's origin https://gaents.com is allowed (preflight at 2026-11-22T02:07:42Z). | Call the API from your server or agent runtime, not from browser JavaScript on your site. | probed 2026-11-22T02:07:46Z: HTTP 403 origin_not_allowed |
HTTP 400 bad_label at sign-up | label is not a string, or longer than 80 characters. | Send a string label of at most 80 characters, or no label. | probed 2026-11-22T02:07:46Z: HTTP 400 bad_label |
HTTP 403 signup_closed | Sign-up is switched off on the API right now. | Pay per call without an account (step 5, HTTP 402), or retry later (status: https://gaents.com/status/). | in the API code, not probed (the API answers it only while sign-up is switched off) |
HTTP 400 amount_out_of_range with min_usd, max_usd | The top-up amount is outside the API's range. | Use an amount from $1.00 to $100.00. | probed 2026-11-22T02:07:47Z: HTTP 400 amount_out_of_range |
HTTP 503 topup_unavailable | The top-up rail is off on the API right now. | Retry later, or pay per call without an account (step 5). | in the API code, not probed (the API answers it only while its top-up rail is off) |
Done: ready for production?
- ☐ The key lives in a secret store or environment variable, never in code. One key per agent:
POST /v1/me/keysmakes one,DELETE /v1/me/keys/<prefix>revokes one. - ☐ Your balance covers your volume:
GET https://api.gaents.com/v1/me(balance_usd); prices per model and job: https://gaents.com/pricing/ . - ☐ You chose the failover mode on purpose (step 4) and log
X-Gaents-Served-Family. - ☐ Your client honours
Retry-Afteron HTTP 503 (nothing is charged) andretry_after_secondson HTTP 429. - ☐ You log
X-ProofandX-Price-Charged-Usdfor every call (step 8 re-checks any of them). - ☐ You checked the model on your own task (step 3).
- ☐ You watch the service state: https://gaents.com/status/ .