Contracts — /api/chain/:slug/contracts*

Programmable state machines that live inside your state machine. Defined in JSON, validated by ContractDefinitionSchema, executed by ContractEngine (in shared/api-core/src/lib/contractEngine.ts). Every successful transition: runs the operator → wraps the result in a ZSP envelope → atomically writes the contract row → appends to the audit entangled state → mints a tally token.

Concept: State Contracts. Source: shared/api-core/src/routes/contracts.ts.

Auth shorthand: operator+ = requireSessionOrMachineKey (a session or the machine's zsm_ key); owner = requireAuth, owner-scoped; public = no auth.

Create & edit

Method	Path	Auth	Notes
POST	/api/chain/:slug/contracts	operator+	Create a contract from a template id.
POST	/api/chain/:slug/contracts/custom	operator+	Create from a raw definition blob (same path, ad-hoc instead of templated).
GET	/api/chain/:slug/contracts	operator+	List contracts on the machine.
GET	/api/chain/:slug/contracts/:id	operator+	Contract + last 20 transitions.
PATCH	/api/chain/:slug/contracts/:id	owner	Edit a contract; bumps current_version_no (history never rewrites).
POST	/api/chain/:slug/contracts/import	operator+	Import a portable contract envelope; runtime state starts clean.
GET	/api/chain/:slug/contracts/:id/export	owner	Portable definition + metadata; omits audit, watermarks, secrets.

Execute & lifecycle

Method	Path	Auth	Notes
POST	/api/chain/:slug/contracts/:id/transition	operator+	Execute a transition (compute + prove + verify + ZSP + chain + tally).
POST	/api/chain/:slug/contracts/:id/dry-run	operator+	Debug what would fire/filter/pass — no audit, no fires, no compute, no charge.
POST	/api/chain/:slug/contracts/:id/fire-now	operator+	Fire a scheduled trigger immediately.
POST	/api/chain/:slug/contracts/:id/pause	operator+	Pause scheduling.
POST	/api/chain/:slug/contracts/:id/resume	operator+	Resume scheduling.
POST	/api/chain/:slug/contracts/:id/skip-next	operator+	Skip the next scheduled fire.
POST	/api/chain/:slug/contracts/:id/freeze	operator+	Stop all fires + clear next_fire; row stays for audit.
POST	/api/chain/:slug/contracts/:id/rollback	operator+	Roll back to a prior version (inserts a new version row; audit stays linear).

Schedule & preview

Method	Path	Auth	Notes
GET	/api/chain/:slug/contracts/:id/next-fires	owner	Upcoming scheduled fire times.
GET	/api/chain/:slug/contracts/:id/preview	owner	Cheap live reactor view (the IDE polls this ~every 5 Zeqonds); no charge.

Audit, verify & versions

Method	Path	Auth	Notes
GET	/api/chain/:slug/contracts/:id/audit	owner	Full transition history.
POST	/api/chain/:slug/contracts/:id/verify	operator+	Verify state-progression integrity.
GET	/api/chain/:slug/contracts/:id/integrity	public	Stored hash vs. live re-hash — detects DB-level tampering.
GET	/api/chain/:slug/contracts/:id/versions	owner	Version list.
GET	/api/chain/:slug/contracts/:id/versions/:n	owner	One version.

Events (SSE)

Method	Path	Auth	Notes
GET	/api/chain/:slug/events	owner	Machine event log.
GET	/api/chain/:slug/events/stream	owner	Server-sent event stream of machine events.
GET	/api/chain/:slug/contracts/:id/transitions/stream	owner	Server-sent stream of one contract's transitions.
GET	/api/admin/contract-events/stats	admin	Aggregate contract-event stats (admin console).

See also

• Contracts concept
• Contract Templates API — the ready-to-deploy templates.
• Tally tokens — the receipt minted on every successful transition.