Agent guidelines

An AI agent can build most of an Aggregator integration: the documentation is published as a machine-readable corpus, the API is small, and the integration track names the evidence each step needs. This page draws the line precisely: what an agent does alone, what stays with a human, and the discipline that keeps an autonomous integration honest on a money path.

What an agent can do alone

With the operator’s authorization and correct organization context:

• Consume the documentation corpus. Fetch /llms-full.txt once and work from it; it contains every approved page on this hub.
• Browse platform state over MCP. The hosted MCP server’s read tools cover the catalog, sessions, transactions, providers, and readiness evidence.
• Write the integration. The wallet callback endpoint per the callback contract, signature verification from the snippets, idempotent storage per Idempotency, and API calls per Code samples or the Node.js SDK.
• Test what it wrote. Unit-test the signature verifier against a known body and secret pair, replay-test the deduplication, run local tests with synthetic data. The human runs remote demos, wallet tests and readiness probes.
• Diagnose failures. Match error responses against the error reference and read retry and backpressure behaviour from the callback page instead of guessing.

What stays with a human

These account and money decisions stay with the human:

1. Registration and KYB. Creating the operator account and completing verification in the cabinet.
2. Issuing the API key. The agg_ key is created by a human in the cabinet and is injected into the approved backend or MCP process through protected secret storage, never as text in a conversation.
3. Registering the callback URL and secret. Wallet settlement configuration is a cabinet decision made by the account owner.
4. Running tests and paying. The human confirms test access, budget and limits, runs remote tests, chooses the current checkout offer and pays. The agent may read available evidence or direct the human to the cabinet.
5. Opening real traffic. The go-live review and the decision to launch belong to the operator’s engineering and compliance people; an agent prepares the evidence, a human signs it.

The hosted MCP endpoint enforces the same split mechanically: its remote actions are denied at call time, so an agent cannot launch sessions or fire readiness probes through it on this Worker. No caller grant or setting enables them.

Source discipline

• The corpus is the source of truth for intent; live responses are the truth for behaviour. Work from llms-full.txt; when the platform’s actual response disagrees with the corpus, trust the response, and report the discrepancy to a human instead of patching over it silently.
• First call is GET /health. https://api.aggregator.gg/health answering {"status": "ok"} separates “my integration is broken” from “the platform is unreachable” before any debugging starts. The path has no /v1 prefix.
• Never invent surface. Use the documented contract and access boundaries; absence from this corpus is not permission to guess a route. No speculative /v1/... paths, no headers the docs never mention.
• Keep diagnostics safe. HTTP status and a fixed allowlist of known codes are enough for routine logs. Raw response bodies, upstream messages, unknown codes and request headers can carry secrets; do not paste them into logs, support messages or chat.
• Match errors on codes. Branch on E-codes from the error reference, not on message text, and retry only the codes the errors page marks transient.

Proving readiness

The path is explanation, registration, integration, verification, purchase, credit and launch. Before any wallet test, the human confirms access, budget and limits; welcome credits are usable only when actually present. The six integration checks in Getting started produce evidence:

1. Key and catalog access work: GET /v1/games returns 200; platforms first create a brand and pass its explicit ref.
2. A demo session renders with no wallet movement.
3. The wallet endpoint verifies a real signed callback, settles it in integer minor units, and answers within 5 seconds.
4. Tamper and replay tests pass: one flipped byte is rejected with 4xx, a replayed trusted integration/organization + provider + transaction identity returns the original status and body with no second movement.
5. A controlled, budgeted round settles end to end, and declines answer 402, never 5xx.
6. GET /v1/transactions reconciles against the agent-built ledger, accounting for internal zero cash legs, free-round movements and reversals. For platforms, arrange brand-level evidence: the machine transactions endpoint has no brand selector.

The human runs remote tests; the agent assembles permitted evidence with its source and freshness. If evidence or a read surface is missing, say not yet verified and direct the human to the cabinet. After testing, the human buys a package and checks server-confirmed paid purchase plus credited balance, then reviews Go-live. A quote, transaction hash or welcome grant is not a completed purchase. Early purchase remains optional; do not invent a new billing or KYB blocker.

Safety boundaries

• The key never enters text. $AGGREGATOR_API_KEY lives in the process environment or a secret manager. It does not appear in source code, commits, logs, prompts, agent transcripts, error messages, or generated documentation; every example on this hub reads it from the environment for exactly that reason.
• Server-side only. The key authenticates a backend. An agent must never emit code that ships the key to a browser, a mobile app, or any third party.
• The callback secret is a second credential. Same rules as the key; it signs money movements, and it is not the API key.
• No autonomous money-path changes after launch. Once real traffic flows, changes to wallet arithmetic, deduplication, or decline handling go through human review; an agent proposes, tests, and documents, a human merges.
• Respect the platform’s pacing. Back off on 429 per Rate limiting instead of rotating keys or parallelising around a bucket; the second bucket is shared by keys of the same issuing user.

Review checklist

Before an agent-built integration is handed to a human for go-live review, the agent confirms:

• The signature verifier uses raw body bytes and a constant-time comparison, and rejects unsigned or tampered requests with 4xx.
• Wallet arithmetic uses exact integer minor units. Follow endpoint-specific units for grant stakes and catalog metadata; do not apply a blanket conversion.
• Persistent deduplication combines trusted integration/organization context, provider_code and transaction_id; tests cover same-ID collisions across providers and atomic settlement/replay.
• Free-round legs branch on is_free, and a grant-funded bet never debits real money.
• Declines answer 402 (or 200 with body "status": 402); duplicates never answer 409.
• The key and callback secret exist only in environment variables or a secret manager. Scan the repository and its history for literal credentials from all supported API-key families: agg_, legacy sk_live_, and legacy sk_test_. Review matches without copying secret values into reports; a prefix search is only a first pass, so also check for the callback secret and encoded or split credentials.
• Every claim in the agent’s readiness report links to evidence: a test run, a transcript, or a reconciliation diff.

The evidence pack, not the agent’s confidence, is what the human reviews.