Skip to main content

​
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.
Today, there is no common language for that operational layer. The document may contain the terms. The workflow tool may coordinate the process. The database may store the status. Application logic may decide what is allowed next. A smart contract, if one exists, may enforce part of the process. The audit trail may live wherever the action happened. That split creates the core problem: there is no shared operational source of truth for what was agreed, who can act, what can happen next, and how the agreement progressed over time. For simple agreements, custom glue can hide that gap. For multi-party workflows, agentic systems, financial commitments, milestone approvals and externally-composed payment flows, grant milestone tracking, approvals, settlement attestations, compliance flows, and onchain coordination, the gap becomes a trust problem. It treats an agreement as a structured artifact that combines human-readable terms with machine-operable state, participant authority, valid inputs, deterministic transitions, and verifiable history. The result is an agreement that humans can review, systems and agents can inspect, and parties can use to interact under shared, verifiable constraints.

​
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: These properties are exposed visually as behavioral maps of the agreement, helping humans and agents understand which states exist, which inputs are valid, who may submit them, and what transitions can occur next. The onchain implementation uses a data-defined state machine to make agreement behavior explicit, inspectable, and verifiable.

​
Benefit and inspection map

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
Agreements can model payment obligations, approvals, balances, invoices, and settlement attestations. Actual value transfer can be composed through external payment rails, escrow contracts, application-layer integrations, or the modular actions extension point. Shodai has a working prototype for payment-transfer actions, planned to be productized soon alongside other extensions.

​
How the system fits together

Agreements Protocol moves from agreement meaning to execution to integration across three layers:
1

Agreement data standard

A common language for terms, variables, participants, inputs, states, transitions, and execution metadata.
2

Onchain execution engine

The onchain implementation uses a data-defined state machine to make agreement behavior explicit, inspectable, and verifiable.
3

Application and API layer

Tooling for validation, deployment preflight, participant mapping, signing, state reads, input history, and monitoring.
Together, these layers let humans, agents, and software coordinate around agreements with shared meaning, explicit execution paths, and verifiable history.

​
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: After your agent answers your immediate question, ask it to offer the hands-on workflow from Run an end-to-end agreement workflow. The workflow should use MCP when MCP tools are available, use the TypeScript SDK when building or testing a TypeScript integration, and report concrete evidence from validation, preflight, signing, deployment, input submission, state, and input history.

​
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

  1. Choose an integration surface: choose TypeScript SDK or MCP for the first run.
  2. Quickstart with TypeScript SDK or Quickstart with MCP: prove auth plus non-destructive write readiness.
  3. Run an end-to-end agreement workflow: run the full lifecycle with the service retainer example.
  4. TypeScript client reference: inspect SDK methods, signing helpers, diagnostics, and exports.
  5. Agreement data standard: understand the agreement definition model.
  6. Author agreement JSON: model the business workflow deliberately.
  7. Validate agreement structure: check the authored artifact before deployment context is added.
  8. Deploy an agreement: preflight deployment values and deploy with a permit signature.
  9. Operate a deployed agreement: read state, submit signed inputs, and inspect history.

​
The agreement lifecycle

​
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 from openapi.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.