The Agreements API is the product integration layer around Agreements Protocol. It gives applications a stable way to turn agreement definitions into deployed, monitored, participant-facing workflows without making every product own contract orchestration, indexing, notification routing, and lifecycle state. The API does not define what an agreement means. Agreement semantics come from the agreement data standard and from the execution engine that interprets those definitions. The API makes those protocol objects usable inside real products. Use the API layer when you want agreement correctness and verifiable execution to show up as ordinary application capabilities: create agreements, attach participants, deploy with signed authorization, read state, submit participant inputs, inspect history, and trigger downstream product behavior.Documentation Index
Fetch the complete documentation index at: https://docs.shodai.network/llms.txt
Use this file to discover all available pages before exploring further.
Why the API matters
Agreements Protocol separates agreement semantics from application delivery. The data standard gives every agreement a uniform language. The onchain execution engine gives deployed agreements constrained, verifiable state transitions. The API connects those layers to the systems where users actually create, accept, operate, and monitor agreements. That matters because most products need more than a contract call. They need draft records, participant context, observers, validation feedback, deployment preflight, state reads, input history, authorization, and notifications. The API provides that supporting layer while keeping the protocol semantics anchored in the agreement definition and execution engine.What the API adds
| Capability | Why it matters |
|---|---|
| Agreement creation and records | Applications can manage draft and deployed agreement records without treating the chain as their only product database. |
| Structural validation | Products can catch missing participant roles, unexpected state IDs, input IDs, and authoring warnings before deployment context is added. |
| Deployment preflight | Teams can review the effective deployment values, participant mappings, observers, contributors, and warnings before any permit is signed. |
| Signed deployment and input submission | The API works with SDK signing helpers so products can preserve wallet authorization while avoiding low-level contract orchestration in every integration. |
| State and history reads | Applications can show current state, accepted inputs, input status, and agreement progression from one integration surface. |
| Participant and observer context | Products can attach participant wallet mappings and observer email context around deployed agreement instances. |
| Monitoring and notifications | Downstream systems can react to agreement lifecycle movement instead of polling raw execution state everywhere. |
The value for product teams
The API lets product teams build agreement experiences around a common execution model instead of rebuilding agreement infrastructure for every workflow.- A marketplace can use the same agreement model for milestone acceptance, rejection, resubmission, and completion.
- A service platform can expose participant actions while preserving state transitions that are constrained by the deployed agreement.
- An operations product can monitor agreement status, history, observers, and notifications without becoming the source of truth for the agreement lifecycle.
- An API integration can use typed client methods and raw API references without depending on private implementation details of the execution engine.
How it preserves trust
The API is designed to support the trust guarantees of the protocol, not replace them.| Trust property | How the API supports it |
|---|---|
| Completeness before execution | Validation and preflight make agreement structure, participant roles, deployment values, and warnings visible before signing. |
| Clear participant context | Participant mappings connect agreement roles to wallet addresses, while observers remain separate application context. |
| Deterministic progression | Signed inputs are submitted against the deployed agreement instance, where the execution engine enforces allowed issuers, states, and transitions. |
| Auditable history | State reads and input history expose the lifecycle that applications need to display, reconcile, and monitor. |
| Substrate independence | Products integrate through agreement definitions and API workflows while the protocol semantics remain separate from a particular application database. |
Where it sits in the system
| Layer | Responsibility |
|---|---|
| Agreement data standard | Defines the common language for agreement prose, variables, participants, inputs, states, transitions, and actions. |
| Onchain execution engine | Interprets deployed agreement definitions and enforces valid inputs, issuers, states, transitions, and history. |
| TypeScript client and signing helpers | Give application code typed methods and EIP-712 helpers for deployment and participant inputs. |
| Agreements API | Provides hosted records, validation, preflight, deployment coordination, state reads, input history, participant context, and integration hooks. |
| Products and API integrations | Build user experiences, operational processes, dashboards, and domain-specific workflows around agreement instances. |
When to use the API
Use the API when your integration needs any of the surrounding product behavior that most agreement workflows require:- hosted agreement records and queries
- draft-to-deployment workflows
- validation and deployment preflight
- participant and observer context
- signed deployment or signed participant inputs through SDK helpers
- current state, input history, and lifecycle monitoring
- notifications or application integrations triggered by agreement movement
What to read next
Quickstart
Confirm API access and make the first authenticated SDK calls.
TypeScript client
Understand the typed client methods, signing helpers, diagnostics, and path helpers.
Deploy an agreement
See the deployment workflow when you are ready to implement it.
Operate a deployed agreement
Read current state, submit signed inputs, and inspect agreement history.