# 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):

```sh step-1
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:

```sh
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.

```sh step-2
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`):

```python step-2-sdk
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

```sh step-3
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:

```sh step-4
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):

```sh step-5-balance
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).

```sh step-5
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`:

```sh
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:

```sh step-6
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`.

```sh step-7
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:

```sh step-8
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/keys` makes 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-After` on HTTP 503 (nothing is charged) and `retry_after_seconds` on HTTP 429.
- [ ] You log `X-Proof` and `X-Price-Charged-Usd` for 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/ .
