AI-agent integration guide

This bundle is designed so a coding agent can complete the sandbox integration without repository access, undocumented endpoints, or production data.

Safe context package#

For repository-free implementation, give the agent only:

• llms.txt and the linked documentation;
• the machine-readable sdk-release.json and its content-addressed, SHA-256-verified server SDK tarball;
• the linked OpenAPI, AsyncAPI, asset contract, integration manifest, and synthetic examples;
• the partner's relevant backend/mobile source with secrets removed;
• placeholder environment variable names, never values.

The public SDK artifact contains the compiled zero-dependency runtime and declarations needed for implementation. It is not credential delivery or production authorization. Before sandbox certification or production use, the agent must also match its digest against Chia's authenticated onboarding release manifest.

Do not provide API keys, webhook secrets, production payloads, raw runtime webhooks, authenticated asset URLs, handoff URLs/fragments, user service-state evidence, analytics, or patient/consumer-health data to an AI system unless separately approved by both parties' policy and applicable law.

Agent reading order#

1. llms.txt for scope and non-negotiable invariants.
2. sdk-release.json for the exact installable artifact, digest, contract bindings, and entry points.
3. Hosted handoff first success for the smallest runtime-only sandbox result.
4. One-hour quickstart for the complete current v2 implementation sequence.
5. Environments before creating configuration.
6. Catalog and handoff and Webhooks before writing handlers.
7. Errors, Settlements, and Go-live before declaring completion.
8. Canonical machine contracts for every field-level decision. If prose and a machine contract appear to disagree, stop and report the conflict; do not guess.

Copyable task prompt#

Implement the Chia Partner API integration from this signed bundle.

Constraints:
- Use the server-only @chiahealth/partner SDK and versioned HTTP/webhook contracts; never use MCP.
- Keep runtime, webhook receiver, and finance in separate credential scopes. Run the webhook-test sender only as an ephemeral runtime-key job; do not invent a fourth credential.
- Never put a Chia secret, authenticated asset URL, SDK, or handoff URL in a browser/mobile bundle or logs.
- Fetch catalog on a backend schedule with ETag; verify and mirror assets atomically at neutral paths.
- Apply fresh partner-owned service-state evidence locally. Render all required fields and exact JIT share/no-share actions.
- After affirmative JIT share consent, call createHandoffSession from your backend with only catalog item, disclosure version, affirmative timestamp, and a persisted UUIDv4 idempotency key. Open the 15-minute URL in the OS browser; never add identity fields, log it, or invent a status endpoint.
- Verify webhooks over exact raw bytes, require `test:true`, dedupe durably, and commit only a no-side-effect receipt; V2 has no live webhook or refresh-job branch.
- In production, accept only closed immutable Finance release rows. Persist by release `id`, require `revision`/`supersedes_id` consistency, never sum a superseded revision, and never infer amount, paid/due state, or counts from live activity, configuration, events, or time. Reject an aggregate count unless its released minimum group size is at least 10; Chia separately enforces composition approval. Sandbox may use only the documented synthetic fixtures.
- Add tests for closed handoff fields/URL/expiry, wrong role/environment, stale
  state, asset corruption, duplicate webhooks, all three synthetic shapes in
  both environments, and the pre-activation production failure. Only after
  written activation, test `livemode:true` and a live production handoff URL
  under `/production/handoff/`.

Before finishing, run the contract checker, SDK/reference tests, link checks, secret scans, and the complete integration definition of done. Report any missing credential/origin or undeployed Chia dependency as a blocker; do not mock it in production or weaken validation.

Agent-safe verification#

Run without credentials:

python3 -B scripts/partner_contracts/check_compatibility.py --validate-all
python3 -B scripts/partner_contracts/check_compatibility.py \
  --self-test api/partner/compatibility-fixtures

Then compile/test the SDK and reference backend with the bundle's pinned toolchain. Credentialed tests must run in isolated processes exactly as shown in the quickstart.

An agent must not claim "live," "deployed," "approved," or "production ready" merely because local tests pass. Completion language must separate:

• contract and local integration complete;
• sandbox connectivity/certification complete;
• production API/webhook certification complete;
• live Chia co-branded purchase workflow activated for the exact release.

The public bundle defines behavior; the signed onboarding and activation receipt binds it to exact deployed origins and credentials.