# Canonical public origin

- Documentation: https://partners.chia.health/
- Generated API and webhook reference: https://partners.chia.health/reference/
- Complete text corpus: https://partners.chia.health/llms-full.txt

- Installable SDK metadata: https://partners.chia.health/sdk-release.json

# Chia Partner API

> Server-to-server marketplace integration for approved care-program catalog
> publications, consent-gated short-lived browser handoff, signed synthetic
> webhook receiver tests, and an isolated finance surface. Production
> credentials support connectivity and synthetic tests before activation;
> catalog and real handoff fail closed. After written activation, handoffs
> enter Chia's live co-branded purchase flow and Chia is merchant of record.
> Production 2.1 finance returns only immutable statement revisions explicitly
> released by Finance.

## Start here

- [Five-minute orientation](https://partners.chia.health/): surface, mental model, and navigation
- [Hosted handoff first success](https://partners.chia.health/docs/hosted-quickstart/): smallest runtime-only sandbox result
- [One-hour integration](https://partners.chia.health/docs/quickstart/): copy-paste sandbox-to-live-production golden path
- [AI-agent instructions](https://partners.chia.health/docs/ai-agents/): safe context, task prompt, and completion language
- [Go-live checklist](https://partners.chia.health/docs/go-live/): technical, operational, and legal definition of done

## Implement by concern

- [Onboarding and signed release receipt](https://partners.chia.health/docs/onboarding/)
- [Environments, authentication, roles, and rotation](https://partners.chia.health/docs/environments/)
- [Catalog caching, asset integrity, rendering, and browser handoff](https://partners.chia.health/docs/catalog-and-handoff/)
- [Webhook verification, durability, delivery, and testing](https://partners.chia.health/docs/webhooks/)
- [Errors, retries, idempotency, and rate limits](https://partners.chia.health/docs/errors/)
- [Settlement pagination and privacy semantics](https://partners.chia.health/docs/settlements/)
- [Troubleshooting and safe escalation](https://partners.chia.health/docs/troubleshooting/)
- [Public component status and incident behavior](https://partners.chia.health/docs/status/)
- [Versions, compatibility, deprecation, and public changelog](https://partners.chia.health/docs/versioning-and-changelog/)
- [Security, privacy, marketplace roles, and legal gates](https://partners.chia.health/docs/security-and-legal/)

## Canonical machine contracts

- [Machine integration manifest](https://partners.chia.health/contracts/v2.1.0/integration-manifest.json): immutable 2.1.0 operation, environment, credential-role, artifact-digest, build-order, and hard-stop map; coding agents read this first
- [OpenAPI 3.1](https://partners.chia.health/contracts/v2.1.0/openapi.yaml): immutable 2.1.0 contract with exactly four JSON operations
- [AsyncAPI 3.0](https://partners.chia.health/contracts/v2.1.0/asyncapi.yaml): immutable 2.1.0 contract with exactly three signed event types
- [Binary asset contract](https://partners.chia.health/contracts/v2.1.0/assets.yaml): immutable 2.1.0 authenticated server-only image retrieval contract
- [Synthetic examples](https://partners.chia.health/examples/index.json)
- [Offline compatibility checker](https://partners.chia.health/tools/check_compatibility.py)

## Separate affiliate tracking contract

The invite-only `chia-s2s-v1` redirect/postback integration is distinct from
the JSON Partner API above. It has separate onboarding, activation, event,
reporting, and program boundaries; do not reuse Partner API credentials or
infer affiliate operations from the OpenAPI contract.

- [Affiliate tracking overview](https://partners.chia.health/docs/affiliate-tracking/)
- [Affiliate integration quickstart](https://partners.chia.health/docs/affiliate-tracking-quickstart/)
- [Affiliate program boundaries](https://partners.chia.health/docs/affiliate-program-boundaries/)
- [Affiliate CSV reporting contract](https://partners.chia.health/docs/affiliate-reporting-contract/)
- [Affiliate read API contract](https://partners.chia.health/docs/affiliate-read-api/): bearer-authenticated read access to the same tracking and reporting facts; a Partner Portal partner makes the key in Settings > Keys (by day until the tracker is live, each sale after), a hand-set integration gets it from the Chia integration owner; never a Partner API key
- [Affiliate read API OpenAPI 3.1](https://partners.chia.health/contracts/affiliate/v1/openapi.yaml): canonical machine contract for `/api/affiliate/v1`, versioned independently of the Partner API v2 release line

## Implementations

- [Machine-readable SDK release](https://partners.chia.health/sdk-release.json): content-addressed tarball URL, SHA-256/SRI, contract bindings, exact install commands, and public safety assertions
- [Server-only TypeScript SDK](https://partners.chia.health/docs/typescript-sdk/)
- [Runnable role-separated reference backend](https://partners.chia.health/docs/reference-backend/)
- [Official renderer, conformance fixture, and OS-browser mobile snippets](https://partners.chia.health/docs/mobile/)

## Non-negotiable invariants

- Use HTTP/OpenAPI and signed webhooks, never MCP, for the Partner API production contract.
- The only JSON operations are `GET /v2/catalog/items`, `POST /v2/handoff-sessions`, `POST /v2/webhook_tests`, and `GET /v2/settlement_summaries`; the only binary operation is authenticated asset GET.
- No patient, care-session, order, payment, prescription, shipment, support, or outcome endpoint/event/callback exists. Do not invent one.
- If activated under a signed agreement, the partner acts only as a
  marketplace publisher, never merchant of record, seller, provider, pharmacy,
  checkout, order, or fulfillment agent.
- Treat `partner_id` as an opaque credential-bound tenant key. V2 requires 2–32 characters matching `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`; compare it exactly and never derive infrastructure or authorization from it.
- Keep runtime, webhook receiver, and finance credentials in mutually isolated server workloads. Run webhook tests as an ephemeral runtime-key job; mobile gets none.
- Fetch catalog on a backend schedule with `ETag`; stream-verify and atomically mirror assets at neutral partner-owned paths. Never fetch per user.
- Apply fresh partner-owned service-state evidence locally; render exact JIT copy; after affirmative share consent call `POST /v2/handoff-sessions` with only catalog item, disclosure version, and the affirmative timestamp, then open the 15-minute URL in the OS browser. Never add identity/contact/device metadata.
- Use the bundle's official renderer projection and conformance fixture. Refresh before action and on restore, keep share and neutral equally accessible, join double taps, reuse the exact body/key after ambiguous failure, and emit no tracking or completion inference.
- Verify webhook HMAC over exact raw bytes, enforce timestamp/environment/header/envelope equality, require `test: true`, dedupe durably, and commit only a no-side-effect receipt. V2 emits no live webhook.
- Fixed service fees never depend on activity. Production 2.1 exposes only immutable Finance-authored statement revisions. Apply `supersedes_id`, never sum a superseded revision, and never infer amount or paid/due state from activity. Never accept a production aggregate count unless its released minimum group size is at least 10 and Chia's internal composition approval passed.
- Never expose or log secrets, raw webhooks, Chia identifiers, authenticated asset URLs, handoff URLs, service state, user telemetry, or consumer-health/patient data.
- Sandbox and production credentials/origins are distinct and never
  interchangeable. Each has separate runtime, finance, and webhook secrets.
  Production runtime supports authentication plus all three synthetic webhook
  tests before activation; written activation enables only the approved
  catalog/handoff. Production finance reads only the separate append-only
  release store and exposes no individual or row-level data.
- Missing deployment, credentials, origins, approvals, or live gates are blockers. Never weaken validation or claim live status to work around them.
- Pin exact contract and SDK releases. Never infer compatibility from `/v2`, a date, or a mutable alias; follow the versioning policy and public changelog.

## Agent verification

An agent without repository access starts at `https://partners.chia.health/sdk-release.json`, verifies the content-addressed SDK tarball exactly as documented, and follows the absolute contract and guide entry points in that file. Credentials and partner configuration are always delivered separately.

Before certification, run this from the signed integration-bundle root and continue only when the single JSON result has `"ok":true` and `"operation_count":4`:

```bash
python3 scripts/partner_contracts/check_compatibility.py --validate-all --output json
```

Then run the pinned SDK/reference tests, local link/snippet checks, secret
scan, all three synthetic webhook shapes in both environments, the expected
pre-activation production catalog/handoff failure, and every applicable item
in the go-live definition. Run the live production catalog/handoff test only
after written activation. Public docs/contracts/SDK and synthetic fixtures are
agent-safe. Secrets and any real user/patient/production data are not.