Chia Partner API

Integrate an approved care-program marketplace without building a healthcare workflow or receiving patient data.

Release status: this bundle describes synthetic sandbox and gated production. Production credentials support connectivity and synthetic webhook certification, but catalog and real handoff fail closed until written activation. After activation, a production handoff opens Chia's real co-branded identity, intake, eligibility, checkout, care, and fulfillment journey; Chia collects payment as merchant of record.

Five-minute orientation#

The partner has one job: present Chia-controlled catalog publications and open the selected Chia experience in the system browser. Chia owns everything after handoff.

scheduled partner backend ──GET catalog──▶ Chia Partner API
         │                                  │
         ├──mirror verified images          ├──scheduled ETag revalidation
         ▼                                  ▼
    partner mobile app ──consent──▶ partner backend ──POST handoff──▶ short-lived browser URL

isolated finance worker ──GET summaries──▶ sandbox fixtures / immutable Finance releases

Catalog and asset work is deliberately off the user-request path. The one deliberate interactive call is a small, idempotent POST /v2/handoff-sessions after affirmative JIT consent; it returns an opaque browser URL valid for 15 minutes.

Capability	Credential	What it returns
`GET /v2/catalog/items`	runtime	Approved cards, presentation rules, disclosure version, session action, and neutral URL
`POST /v2/handoff-sessions`	runtime	Opaque 15-minute URL after affirmative consent; synthetic in sandbox, real Chia purchase journey in production
`POST /v2/webhook_tests`	runtime	Acceptance of one signed synthetic delivery request
`GET /v2/settlement_summaries`	finance	Synthetic sandbox fixtures; append-only immutable production statement revisions released by Finance
`GET /a/{opaque_asset_id}`	runtime, separate asset origin	One digest-bound image for backend mirroring
Signed synthetic test delivery	webhook secret	Explicitly requested `test:true` `endpoint.test`, `catalog.updated`, or `settlement_summary.finalized`; never a live business event

There is no patient, care-session, payment, order, prescription, fulfillment, shipment, support, or outcome resource. The partner is a paid publisher—not the seller, merchant of record, provider, pharmacy, checkout, or order agent.

Credentials are tenant-scoped, environment-scoped, and role-scoped. A credential can access only its assigned partner tenant, and the catalog publications, disclosures, policy links, return configuration, and <Partner> × Chia co-brand copy shown to a user are selected from that credential-bound tenant configuration. Never share credentials between partners or environments.

Pick your path#

I want the smallest working result: follow Hosted handoff first success using only the sandbox runtime workload after signed onboarding.
I have five minutes to understand the product: read this page, Environments and credentials, and the data boundary.
I want a working sandbox integration: follow the one-hour quickstart.
I am implementing the web or mobile experience: use the official renderer in Catalog, assets, and handoff plus the mobile snippets and conformance fixture.
I am implementing reliability: use Webhooks, Errors, retries, and idempotency, and Troubleshooting.
I am implementing finance: read Settlement summaries.
I am planning an upgrade: read Versions, compatibility, and changelog and pin the exact reviewed release.
I am preparing launch: complete the Go-live checklist and Onboarding receipt.
I am an AI coding agent: start with llms.txt, then follow AI-agent instructions.

The golden path#

Verify the signed integration bundle and install the exact bundled TypeScript SDK tarball.
Deploy three isolated secret domains: runtime catalog, webhook receiver, and finance. Run webhook tests as an ephemeral job in the runtime domain; it deliberately reuses the runtime key.
Fetch the catalog on a schedule with ETag; mirror each image only after full integrity verification.
Apply the partner's fresh local service-state gate and use the official renderer contract to show every required field exactly.
On share consent, have your backend create a short-lived handoff using only catalog item, disclosure version, and affirmative timestamp; open the returned URL in the OS browser. Open the neutral URL directly on no-share.
Verify, deduplicate, and acknowledge webhooks; synthetic events always take the zero-side-effect branch.
Certify the sandbox finance fixtures from the isolated finance worker; never treat them as real accounting data.
Repeat with separate production runtime, finance, and webhook credentials. Before written activation, confirm authentication, fail-closed catalog and handoff behavior, all three test:true webhook shapes, and the production finance traversal. After written activation, confirm the approved live catalog and co-branded purchase handoff. Persist releases by ID, apply supersedes_id, and never sum a superseded revision.

You are done when the integration definition of done passes in both environments and the signed activation receipt identifies the exact production release.

Contract and support#

Machine contracts are canonical: OpenAPI, AsyncAPI, and the asset contract. Repository-free integrations start with the machine-readable public SDK release, which binds a content-addressed installable package to those contracts. Read the versioning and changelog policy before upgrading. The SDK guide is in sdks/typescript-partner; the runnable reference is in examples/partner-reference-backend.

Every application-level API response includes Chia-Request-Id. Record it when present with the HTTP status and error code—never credentials, response bodies, webhook bodies, or handoff URLs—check the public service status, and escalate through the named Chia integration support contact in the signed onboarding receipt. An opaque edge failure may have no Chia request ID; use a partner-owned correlation ID and UTC time instead.

The D2C MCP surface is not this contract. Use only the versioned HTTP API, signed webhooks, and consent-gated handoff documented here.