# 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.

```text
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](https://partners.chia.health/docs/hosted-quickstart/) using only the sandbox runtime workload after signed onboarding.
- **I have five minutes to understand the product:** read this page, [Environments and credentials](https://partners.chia.health/docs/environments/), and the [data boundary](https://partners.chia.health/docs/security-and-legal/#the-boundary-in-one-table).
- **I want a working sandbox integration:** follow the [one-hour quickstart](https://partners.chia.health/docs/quickstart/).
- **I am implementing the web or mobile experience:** use the official renderer in [Catalog, assets, and handoff](https://partners.chia.health/docs/catalog-and-handoff/) plus the [mobile snippets and conformance fixture](https://partners.chia.health/docs/mobile/).
- **I am implementing reliability:** use [Webhooks](https://partners.chia.health/docs/webhooks/), [Errors, retries, and idempotency](https://partners.chia.health/docs/errors/), and [Troubleshooting](https://partners.chia.health/docs/troubleshooting/).
- **I am implementing finance:** read [Settlement summaries](https://partners.chia.health/docs/settlements/).
- **I am planning an upgrade:** read [Versions, compatibility, and changelog](https://partners.chia.health/docs/versioning-and-changelog/) and pin the exact reviewed release.
- **I am preparing launch:** complete the [Go-live checklist](https://partners.chia.health/docs/go-live/) and [Onboarding receipt](https://partners.chia.health/docs/onboarding/).
- **I am an AI coding agent:** start with [`llms.txt`](https://partners.chia.health/llms.txt), then follow [AI-agent instructions](https://partners.chia.health/docs/ai-agents/).

## The golden path

1. Verify the signed integration bundle and install the exact bundled TypeScript SDK tarball.
2. 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.
3. Fetch the catalog on a schedule with `ETag`; mirror each image only after full integrity verification.
4. Apply the partner's fresh local service-state gate and use the official renderer contract to show every required field exactly.
5. 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.
6. Verify, deduplicate, and acknowledge webhooks; synthetic events always take the zero-side-effect branch.
7. Certify the sandbox finance fixtures from the isolated finance worker; never treat them as real accounting data.
8. 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](https://partners.chia.health/docs/go-live/#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](https://partners.chia.health/openapi.yaml), [AsyncAPI](https://partners.chia.health/asyncapi.yaml), and the [asset contract](https://partners.chia.health/asset-contract.yaml). Repository-free integrations start with the [machine-readable public SDK release](https://partners.chia.health/sdk-release.json), which binds a content-addressed installable package to those contracts. Read the [versioning and changelog policy](https://partners.chia.health/docs/versioning-and-changelog/) before upgrading. The SDK guide is in [`sdks/typescript-partner`](https://partners.chia.health/docs/typescript-sdk/); the runnable reference is in [`examples/partner-reference-backend`](https://partners.chia.health/docs/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](https://partners.chia.health/docs/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.