gaents Dashboard

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:

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 seeWhyFixChecked
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_keyThe 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_failoverThe 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_paramThe 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_requiredNo 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_objectThe 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_usdThe 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-AfterNo 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_secondsToo 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 contentThe 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-uplabel 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_closedSign-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_usdThe 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_unavailableThe 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?