Why Agreements Protocol
Agreements are how people, organizations, and agents coordinate around shared commitments.From static records to operational agreements
Traditional agreements are passive records. They describe what parties accepted, but the operational rules usually live somewhere else: in applications, workflows, databases, or custom smart contracts. Shodai makes that operational layer part of the agreement definition itself. A Shodai agreement can define what was agreed, who the parties are, who can act, what inputs are valid, what state the agreement is in, what can happen next, and how the history can be verified. The current implementation realizes this through a common agreement data standard, an onchain execution model, and an API/app layer for deploying and operating agreements.An agreement should not only record what parties accepted; it should define who can act, what can happen next, and how progression can be verified.
What Agreements Protocol provides
Agreements Protocol closes the gap between what parties agree to and how that agreement is reliably, verifiably carried forward. It defines agreements as shared artifacts with:| Capability | What it provides |
|---|---|
| Reviewable meaning | Human-readable terms people can review, paired with structured data systems and agents can inspect. |
| Authority | Declared participants, replicable templates, immutable onchain deployment. |
| Valid interaction | Valid inputs, issuer conditions, explicit states, and deterministic transitions. |
| Verifiable history | Deployment records, accepted inputs, state progression, and auditable lifecycle history. |
| Extensible execution | Separation between agreement definition and execution engine, with room for profiles, verifiers, actions, SDKs, APIs, and application layers. |
Benefit and inspection map
| Protocol property | What provides it | Where to inspect |
|---|---|---|
| Reviewable meaning | Human-readable terms plus structured agreement JSON | Agreement data standard |
| Explicit authority | Participants, variables, and input issuer rules | Author Agreement JSON |
| Valid next actions | Inputs, conditions, and transitions | Author Agreement JSON / Operate a Deployed Agreement |
| Verifiable history | Onchain state progression and events | Onchain execution engine / EIP-712 Signing Reference |
| Predictable behavior | Fixed deployed definition and deterministic execution | Deploy an Agreement / Onchain execution engine |
| Extensible effects | Actions, modular extensions, and application-layer integrations | Architecture overview |
Current boundaries:
- the core engine does not currently custody funds or natively transfer ETH/ERC-20 assets
- the documented happy path uses the API-assisted deployment and operation flow
- direct onchain operation should be documented and inspected through the onchain/EIP-712 references
- programmatic agreement generation is possible because agreements are data, but generated agreements should still be valid for the current EVM/onchain implementation and reviewable before deployment
How the system fits together
Agreements Protocol moves from agreement meaning to execution to integration across three layers:Agreement data standard
A common language for terms, variables, participants, inputs, states, transitions, and execution metadata.
Onchain execution engine
The onchain implementation uses a data-defined state machine to make agreement behavior explicit, inspectable, and verifiable.
Using these docs with an AI agent
These docs are designed to help an AI coding agent answer your question, find the right implementation path, and move from explanation to a working experiment. The pages below are useful discovery starting points, not a required reading order:- llms.txt for the available Markdown pages and OpenAPI.
- Choose an integration surface for deciding between the TypeScript SDK and MCP first-run paths.
- Quickstart with TypeScript SDK for a TypeScript first flight through auth, validation, preflight, and deploy-permit signing readiness.
- Quickstart with MCP for an agent/MCP first flight through authenticated tools and deploy typed-data preparation.
- Run an end-to-end agreement workflow for the full lifecycle after either quickstart.
- TypeScript client reference for SDK methods, signing helpers, wallet/RPC requirements, and diagnostics.
- Architecture for the product and protocol model.
- Agreement data standard for the agreement definition that humans read, agents inspect, and execution engines enforce.
Where to go next
Start with Choose an integration surface, then run one first-flight quickstart. After that, use Run an end-to-end agreement workflow to exercise the full lifecycle.Choose an integration surface
Decide between the TypeScript SDK and MCP first-run paths.
Quickstart with TypeScript SDK
Authenticate, validate an example, preflight deployment, and sign a deploy permit without deploying.
Quickstart with MCP
Configure hosted MCP, call authenticated tools, and prepare deploy typed data without private-key custody.
Run an end-to-end workflow
Deploy, submit a signed input, read state, and inspect history.
Architecture
See how agreement definitions, SDKs, onchain execution, history, and APIs fit together.
TypeScript client reference
Reference typed methods, signing helpers, diagnostics, path helpers, and exports.
The default path
- Choose an integration surface: choose TypeScript SDK or MCP for the first run.
- Quickstart with TypeScript SDK or Quickstart with MCP: prove auth plus non-destructive write readiness.
- Run an end-to-end agreement workflow: run the full lifecycle with the service retainer example.
- TypeScript client reference: inspect SDK methods, signing helpers, diagnostics, and exports.
- Agreement data standard: understand the agreement definition model.
- Author agreement JSON: model the business workflow deliberately.
- Validate agreement structure: check the authored artifact before deployment context is added.
- Deploy an agreement: preflight deployment values and deploy with a permit signature.
- Operate a deployed agreement: read state, submit signed inputs, and inspect history.
The agreement lifecycle
| Phase | What you do | SDK entry point | Start here |
|---|---|---|---|
| Author | Model the agreement text, variables, participants, states, inputs, and transitions. | Agreement JSON artifact | Author Agreement JSON |
| Validate | Check authored JSON before combining it with deployment context. | client.validateTemplate(...) | Validate Agreement Structure |
| Deploy | Combine authored JSON with initValues, participants, observers, and a deployment permit. | client.validateDeployment(...), deployAgreementWithPermit(...) | Deploy an Agreement |
| Operate | Read current state, submit signed inputs, and confirm lifecycle movement. | client.getAgreementState(...), submitAgreementInputWithPermit(...) | Operate a Deployed Agreement |
Where examples and reference fit
Simple Agreement and Complex Agreement are complete agreement JSON artifacts you can inspect or adapt before validating and deploying. Use Run an end-to-end agreement workflow when you want a guided run of the complex service retainer example through validation, deployment, operation, state, and history. Use the API Reference group in the sidebar for generated request and response details fromopenapi.json. Use EIP-712 Signing Reference when you are constructing typed data directly, verifying SDK helper behavior, or debugging a signing mismatch. Use Errors and troubleshooting when a request fails.