> ## 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.
# Overview
> Understand how Agreements Protocol gives agreements shared meaning, explicit execution paths, and verifiable history.
For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).
## 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:
| 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. |
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
| Protocol property | What provides it | Where to inspect |
| -------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Reviewable meaning | Human-readable terms plus structured agreement JSON | [Agreement data standard](/system-architecture/data-standard) |
| Explicit authority | Participants, variables, and input issuer rules | [Author Agreement JSON](/workflow/author-agreement-json#author-states-inputs-issuers-and-transitions-as-workflow) |
| Valid next actions | Inputs, conditions, and transitions | [Author Agreement JSON](/workflow/author-agreement-json) / [Operate a Deployed Agreement](/workflow/operate-a-deployed-agreement) |
| Verifiable history | Onchain state progression and events | [Onchain execution engine](/system-architecture/on-chain) / [EIP-712 Signing Reference](/reference/eip-712-signing) |
| Predictable behavior | Fixed deployed definition and deterministic execution | [Deploy an Agreement](/workflow/deploy-an-agreement) / [Onchain execution engine](/system-architecture/on-chain) |
| Extensible effects | Actions, modular extensions, and application-layer integrations | [Architecture overview](/system-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
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:
A common language for terms, variables, participants, inputs, states, transitions, and execution metadata.
The onchain implementation uses a data-defined state machine to make agreement behavior explicit, inspectable, and verifiable.
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:
* [llms.txt](https://docs.shodai.network/llms.txt) for the available Markdown pages and OpenAPI.
* [Choose an integration surface](/integration-surfaces) for deciding between the TypeScript SDK and MCP first-run paths.
* [Quickstart with TypeScript SDK](/sdks/quickstart-with-typescript-sdk) for a TypeScript first flight through auth, validation, preflight, and deploy-permit signing readiness.
* [Quickstart with MCP](/sdks/quickstart-with-mcp) for an agent/MCP first flight through authenticated tools and deploy typed-data preparation.
* [Run an end-to-end agreement workflow](/examples/end-to-end-workflow) for the full lifecycle after either quickstart.
* [TypeScript client reference](/sdks/typescript-client) for SDK methods, signing helpers, wallet/RPC requirements, and diagnostics.
* [Architecture](/system-architecture/overview) for the product and protocol model.
* [Agreement data standard](/system-architecture/data-standard) for the agreement definition that humans read, agents inspect, and execution engines enforce.
After your agent answers your immediate question, ask it to offer the hands-on workflow from [Run an end-to-end agreement workflow](/examples/end-to-end-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.
Answer the user's immediate question from source docs first. Read any additional docs, generated API reference pages, OpenAPI details, or Markdown exports needed for accuracy. For first experiments, choose between Quickstart with TypeScript SDK and Quickstart with MCP before attempting the end-to-end workflow. For the default testnet SDK flow, create `ApiClient` with `environment: 'testnet'` and the user's API key; do not ask for a custom base URL unless the user explicitly targets a custom host. Report concrete evidence such as validation output, deployment preflight results, signer/deadline/signature fields, agreement ID/address/chain when deployed, submitted input status, state changes, and input-history records.
If MCP is involved, distinguish docs/search MCP from Agreements execution MCP. Use docs-domain MCP surfaces only for documentation retrieval. Use `https://shodai.network/mcp` for Agreements tools that author, validate, deploy, or operate agreements.
## Where to go next
Start with [Choose an integration surface](/integration-surfaces), then run one first-flight quickstart. After that, use [Run an end-to-end agreement workflow](/examples/end-to-end-workflow) to exercise the full lifecycle.
Decide between the TypeScript SDK and MCP first-run paths.
Authenticate, validate an example, preflight deployment, and sign a deploy permit without deploying.
Configure hosted MCP, call authenticated tools, and prepare deploy typed data without private-key custody.
Deploy, submit a signed input, read state, and inspect history.
See how agreement definitions, SDKs, onchain execution, history, and APIs fit together.
Reference typed methods, signing helpers, diagnostics, path helpers, and exports.
## The default path
1. [Choose an integration surface](/integration-surfaces): choose TypeScript SDK or MCP for the first run.
2. [Quickstart with TypeScript SDK](/sdks/quickstart-with-typescript-sdk) or [Quickstart with MCP](/sdks/quickstart-with-mcp): prove auth plus non-destructive write readiness.
3. [Run an end-to-end agreement workflow](/examples/end-to-end-workflow): run the full lifecycle with the service retainer example.
4. [TypeScript client reference](/sdks/typescript-client): inspect SDK methods, signing helpers, diagnostics, and exports.
5. [Agreement data standard](/system-architecture/data-standard): understand the agreement definition model.
6. [Author agreement JSON](/workflow/author-agreement-json): model the business workflow deliberately.
7. [Validate agreement structure](/workflow/validate-agreement-structure): check the authored artifact before deployment context is added.
8. [Deploy an agreement](/workflow/deploy-an-agreement): preflight deployment values and deploy with a permit signature.
9. [Operate a deployed agreement](/workflow/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](/workflow/author-agreement-json) |
| Validate | Check authored JSON before combining it with deployment context. | `client.validateTemplate(...)` | [Validate Agreement Structure](/workflow/validate-agreement-structure) |
| Deploy | Combine authored JSON with `initValues`, participants, observers, and a deployment permit. | `client.validateDeployment(...)`, `deployAgreementWithPermit(...)` | [Deploy an Agreement](/workflow/deploy-an-agreement) |
| Operate | Read current state, submit signed inputs, and confirm lifecycle movement. | `client.getAgreementState(...)`, `submitAgreementInputWithPermit(...)` | [Operate a Deployed Agreement](/workflow/operate-a-deployed-agreement) |
## Where examples and reference fit
[Simple Agreement](/examples/simple) and [Complex Agreement](/examples/complex) are complete agreement JSON artifacts you can inspect or adapt before validating and deploying. Use [Run an end-to-end agreement workflow](/examples/end-to-end-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](/reference/eip-712-signing) when you are constructing typed data directly, verifying SDK helper behavior, or debugging a signing mismatch. Use [Errors and troubleshooting](/reference/errors-and-troubleshooting) when a request fails.