network.shodai/agreements

Official11 tools

by CNSLabs · TypeScript

Shodai Agreements

Author, validate, deploy, and operate Shodai on-chain agreements.

Deploy and manage on-chain smart contract agreements on Shodai.

Captured live from the server via tools/list.

list_agreements

Lists agreement summaries visible to the current API key. Supports pagination (cursor + limit), filtering by chain and state, and sorting. Returns summaries only; use get_agreement for the full record.

Parameters (11)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
chainIdinteger
Filter by EVM chain ID (e.g. 59141 for Linea Sepolia).
statestring
Filter by current lifecycle state ID.
createdAfterstring
ISO 8601 timestamp; only agreements created at or after this time.
createdBeforestring
ISO 8601 timestamp; only agreements created at or before this time.
updatedAfterstring
ISO 8601 timestamp; only agreements updated at or after this time.
updatedBeforestring
ISO 8601 timestamp; only agreements updated at or before this time.
sortBystring
Sort field (single field only).
sortDirectionstring
Sort direction; defaults to desc.
limitinteger
Page size (max 100).
cursorstring
Opaque pagination cursor from a previous response (pageInfo.nextCursor).

get_agreement

Returns a single agreement record, including the full authored agreement JSON and hosted record context (participants, observers, owner, deployment address).

Parameters (2)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementIdstringrequired
Agreement record ID, as returned by list_agreements (not the on-chain address).

get_agreement_document

Returns the rendered hosted prose document for an agreement by documentId, including content type, display name, chain, docUri, and agreement record references. Use documentId from list_agreements/get_agreement or from prepare_deployment_typed_data.

Parameters (2)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
documentIdstringrequired
Hosted agreement document ID, as returned by list_agreements/get_agreement or prepare_deployment_typed_data.

get_agreement_state

Returns the current state of an agreement. For deployed agreements, interpret the state against the states defined in the authored agreement lifecycle (execution.states). Use this to poll for transitions after submitting an input.

Parameters (2)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementIdstringrequired
Agreement record ID, as returned by list_agreements (not the on-chain address).

get_input_history

Returns recorded input submissions for an agreement, with pagination and filtering. Use this to inspect which events have been submitted and whether each is PENDING, MINED, or FAILED.

Parameters (6)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementIdstringrequired
Agreement record ID, as returned by list_agreements (not the on-chain address).
inputIdstring
Filter by input ID as defined in the agreement JSON (execution.inputs).
statusstring
Filter by submission status.
limitinteger
Page size (max 100).
cursorstring
Opaque pagination cursor from a previous response (pageInfo.nextCursor).

validate_agreement

Checks only the authored agreement JSON document and returns participant variable keys, input IDs, state IDs, and warnings. This does not validate deployment values, participant wallet addresses, signer, or permit data — use preflight_deployment for that. Iterate on the agreement JSON until this returns no blocking warnings. Requires the agreements.write scope.

Parameters (2)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementobjectrequired
Complete authored agreement JSON document with metadata, variables, content, and execution sections. See the simple/complex example resources for the authoritative shape.

preflight_deployment

Checks whether authored agreement JSON plus target chain, deployment values, participant wallet mappings, and observer context are ready for deployment. This does not deploy the agreement and does not require a signature. Always run this before signing a deploy permit. Requires the agreements.write scope.

Parameters (6)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementobjectrequired
Complete authored agreement JSON document with metadata, variables, content, and execution sections. See the simple/complex example resources for the authoritative shape.
chainIdinteger
Target EVM chain ID for deployment.
initValuesobject
Deployment-time values for variables referenced by execution.initialize.data.
participantsarray
Wallet mappings for participant variables.
observersarray
Observer email addresses for the deployed agreement.

deploy_agreement

Deploys authored agreement JSON using an EIP-712 permit; the API submits the on-chain transaction and returns the deployed agreement record. Provide a pre-signed permit (signer, deadline, signature), or call prepare_deployment_typed_data first to obtain the payload to sign. Always run preflight_deployment before deploying. Requires the agreements.write scope.

Parameters (14)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementobjectrequired
Complete authored agreement JSON document with metadata, variables, content, and execution sections.
displayNamestringrequired
Human-readable name for the deployed agreement record.
chainIdinteger
Target EVM chain ID (e.g. 59141 for Linea Sepolia).
initValuesobject
Deployment-time values for variables referenced by execution.initialize.data.
participantsarray
Wallet mappings for participant variables.
observersarray
Observer email addresses.
docUristring
Optional document URI recorded on-chain with the agreement.
documentIdstring
Optional hosted document ID paired with docUri for GET /v0/agreements/documents/{documentId}.
signerstring
Wallet address (0x...) that signed the permit.
deadlineinteger
Permit deadline in unix seconds. Must match the signed payload.
signatureVinteger
Permit signature v component (27 or 28).
signatureRstring
Permit signature r component (0x... 32 bytes).
signatureSstring
Permit signature s component (0x... 32 bytes).

submit_input

Submits a signed input to a deployed agreement, advancing its on-chain lifecycle. The input ID and values must match an input defined by the agreement JSON, and the signer must be allowed by that input. Provide a pre-signed permit (signer, deadline, signature), or call prepare_input_typed_data first. Requires the agreements.write scope.

Parameters (9)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementIdstringrequired
Agreement record ID of a deployed agreement.
inputIdstringrequired
Input ID defined by the agreement JSON (execution.inputs).
valuesobjectrequired
Values matching the input schema defined by the agreement JSON.
signerstring
Wallet address (0x...) that signed the permit.
deadlineinteger
Permit deadline in unix seconds. Must match the signed payload.
signatureVinteger
Permit signature v component (27 or 28).
signatureRstring
Permit signature r component (0x... 32 bytes).
signatureSstring
Permit signature s component (0x... 32 bytes).

prepare_deployment_typed_data

Builds the exact EIP-712 payload that must be signed to authorize deployment of the given agreement JSON. Sign the returned typedData with the deploying wallet (eth_signTypedData_v4 / viem signTypedData), then call deploy_agreement with signer, deadline, and the signature components. No transaction is sent and nothing is stored. Reads the signer nonce from the target chain.

Parameters (10)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementobjectrequired
Complete authored agreement JSON document with metadata, variables, content, and execution sections.
chainIdintegerrequired
Target EVM chain ID (e.g. 59141 for Linea Sepolia).
signerAddressstringrequired
Wallet address (0x...) that will sign and own the deployment.
deadlineinteger
Permit deadline in unix seconds; defaults to one hour from now.
initValuesobject
Deployment-time init values (must match the later deploy_agreement call).
participantsarray
Wallet mappings for participant variables.
observersarray
Observer email addresses.
docUristring
Document URI (must match the later deploy_agreement call).
documentIdstring
Hosted document ID. If omitted with docUri, no hosted document ID is stored; if both are omitted, the server generates both values.

prepare_input_typed_data

Builds the exact EIP-712 payload that must be signed to authorize submitting an input to a deployed agreement. Sign the returned typedData with a wallet allowed by the input definition, then call submit_input with signer, deadline, and the signature components. No transaction is sent and nothing is stored. Reads the agreement record and signer nonce.

Parameters (6)

environmentstringrequired
Agreements API environment for this tool call. API keys only work in the environment where they were created.
agreementIdstringrequired
Agreement record ID of a deployed agreement.
inputIdstringrequired
Input ID defined by the agreement JSON (execution.inputs).
valuesobjectrequired
Values matching the input schema (must match the later submit_input call).
signerAddressstringrequired
Wallet address (0x...) that will sign the input permit.
deadlineinteger
Permit deadline in unix seconds; defaults to one hour from now.

README.md10 KBView on GitHub

Shodai Agreements SDK + MCP

Shodai turns agreement definitions into machine-readable, verifiable coordination workflows for humans, products, and AI agents. Agreements carry readable terms plus participants, valid inputs, states, transitions, and history.

This repository supports builders using the TypeScript SDK, agents or tools using MCP, and the canonical Shodai Reference App built on top of the SDK.

Start Here

Need	Start
Understand Shodai	Shodai Home · Developer Docs · Demo App
Get access	Dev Portal / API keys
Build	Choose SDK vs MCP · MCP quickstart · TypeScript SDK quickstart · End-to-end workflow

Hosted MCP: https://shodai.network/mcp is the Shodai Agreements execution MCP endpoint. It uses Streamable HTTP, bearer API-key auth, an environment tool argument, environment-scoped keys, and no hosted private-key custody.

Packages and apps: @cns-labs/agreements-api-client · @cns-labs/agreements-mcp-server · agreements-api-playground · shodai-reference-app

Why Builders Use Shodai Agreements

Shared agreement state that humans, applications, and agents can inspect.
Deterministic next actions from authored states, inputs, issuers, and transitions.
Validation and deployment preflight before signatures.
EIP-712 signed authorization for deployment and participant inputs.
State and input history for receipts and monitoring.
Less repeated contract orchestration, indexing, and participant workflow plumbing.

Choose Your Path

Path	Use it when	First success
MCP / agent tools	An agent or MCP-capable client will work with agreements through hosted Streamable HTTP or local stdio.	Authenticate, read or list where permitted, validate an example, preflight deployment, and prepare deploy typed data.
TypeScript SDK	You are building a TypeScript application or service.	Authenticate, read or list agreements, validate an example, preflight deployment, and prove local EIP-712 signing readiness.

Both paths converge on the same agreement lifecycle. After one quickstart works, run the end-to-end workflow.

Hosted MCP Endpoint

Configure Shodai as a remote Streamable HTTP MCP server:

text

URL:
https://shodai.network/mcp

Auth:
Authorization: Bearer $SHODAI_API_KEY

Key shape:
cns_pk_...

Required API-calling tool argument:
environment: "testnet" | "production"

API keys only work in the environment where they were created. Hosted MCP never receives private keys; write tools use externally signed EIP-712 permits or typed-data preparation.

An ordinary browser GET to /mcp may return 405 because the endpoint expects MCP protocol requests. MCP surfaces on docs.shodai.network are for docs and search only; https://shodai.network/mcp is the Agreements execution endpoint.

MCP quickstart: docs.shodai.network/sdks/quickstart-with-mcp
MCP package docs: packages/agreements-mcp-server/README.md
Execution server card: shodai.network/.well-known/mcp/server-card.json
MCP catalog: shodai.network/.well-known/mcp/catalog.json

What This Repository Contains

Package or app	Location	Purpose
`@cns-labs/agreements-api-client`	`packages/agreements-api-client`	Typed REST client for the Agreements API with `viem` permit-signing helpers.
`@cns-labs/agreements-mcp-server`	`packages/agreements-mcp-server`	Local MCP server package aligned with the hosted Agreements execution MCP surface.
`agreements-api-playground`	`apps/agreements-api-playground`	Reference Vite app for browser API experimentation and SDK workflow examples.
`shodai-reference-app`	`apps/shodai-reference-app`	Full-stack React/Nest/Mongo reference implementation for developer platform auth, Agreements API usage, agreement lifecycle UX, signing, persistence, and webhook reconciliation.

Install the TypeScript SDK

Most TypeScript consumers should install the published npm package rather than this monorepo:

bash

npm install @cns-labs/agreements-api-client

Add viem if you want the built-in permit-signing helpers for deploy and input submission:

bash

npm install @cns-labs/agreements-api-client viem

Create a client with a named Shodai environment:

const client = new ApiClient({
  environment: 'testnet',
  apiKey: process.env.AGREEMENTS_API_KEY,
});

SDK usage and API lifecycle docs live in packages/agreements-api-client/README.md. For constructor options, methods, signing helpers, diagnostics, and exports, see the TypeScript client reference.

Run MCP Locally

Use the published MCP package for local stdio clients:

json

{
  "mcpServers": {
    "shodai-agreements": {
      "command": "npx",
      "args": ["-y", "@cns-labs/agreements-mcp-server"],
      "env": {
        "AGREEMENTS_API_KEY": "YOUR_API_KEY",
        "AGREEMENTS_API_ENVIRONMENT": "testnet"
      }
    }
  }
}

Local stdio mode uses AGREEMENTS_API_ENVIRONMENT; hosted MCP uses the environment tool argument. See packages/agreements-mcp-server/README.md for self-hosting, environment variables, tools, resources, prompts, and Inspector usage.

Agreement Lifecycle

Phase	TypeScript SDK	MCP
Author agreement JSON	Use complete agreement JSON artifacts and examples.	Read example resources or use the authoring prompt.
Validate structure	`client.validateTemplate(...)`	`validate_agreement`
Preflight deployment	`client.validateDeployment(...)`	`preflight_deployment`
Prepare or sign deployment permit	SDK signing helpers with `viem`	`prepare_deployment_typed_data` and external signing
Deploy	`deployAgreementWithPermit(...)` or `client.deployWithPermit(...)`	`deploy_agreement` with signed permit fields
Read state	`client.getAgreementState(...)`	`get_agreement_state`
Prepare or sign input permit	SDK input-signing helpers	`prepare_input_typed_data` and external signing
Submit input	`submitAgreementInputWithPermit(...)` or `client.submitAgreementInput(...)`	`submit_input` with signed permit fields
Inspect history	`client.listAgreementInputs(...)`	`get_input_history`

For a guided run through validation, deployment, signed input submission, state reads, and input history, use the end-to-end workflow.

Agreements API Environments

The SDK prefers a named environment instead of a raw host:

const client = new ApiClient({
  environment: 'testnet',
  apiKey: process.env.AGREEMENTS_API_KEY,
});

Built-in mappings:

testnet -> https://test-api.shodai.network
production -> https://api.shodai.network

API keys are environment-scoped. Use a testnet key with testnet and a production key with production.

The client still supports baseUrl as an advanced override for local proxies, internal gateways, or non-standard deployments. It continues to add /v0/* automatically.

Local Development

bash

# from the repository root
pnpm install
pnpm build
pnpm dev

The default dev command starts the Shodai Reference App. Its backend defaults to http://localhost:4199 and its frontend defaults to http://localhost:5184/agreements/.

Stop the reference app dev stack with:

bash

pnpm dev:stop

See apps/shodai-reference-app/README.md for the required local environment files.

Run the API playground explicitly with:

bash

pnpm dev:playground

The playground defaults to http://localhost:5176. If that port is already in use, start the playground on another port:

bash

pnpm --filter agreements-api-playground exec vite --host 127.0.0.1 --port 4176

For local browser development, the playground is environment-first and defaults to testnet. Use the in-app environment selector to switch between hosted testnet and production API targets.

Optional package-specific validation commands:

bash

pnpm --filter @cns-labs/agreements-api-client run lint
pnpm --filter @cns-labs/agreements-mcp-server test

See apps/agreements-api-playground/README.md for the full environment configuration.

Boundaries

Hosted MCP does not hold private keys. OAuth/session auth and x402 payments are not current setup paths. Shodai agreements do not claim legal finality or fully autonomous enforcement. Shodai does not move value without authorized signed inputs.

Open Source Project Notes

API client consumer docs: packages/agreements-api-client/README.md
API client maintainer notes: packages/agreements-api-client/DEVELOPMENT.md
MCP server docs: packages/agreements-mcp-server/README.md
Playground docs: apps/agreements-api-playground/README.md
Root license: Apache-2.0
MCP package license: MIT

Install

claude_desktop_config.json

{
  "mcpServers": {
    "agreements": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://shodai.network/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.