Run an end-to-end agreement workflow

Use this tutorial after Quickstart with TypeScript SDK or Quickstart with MCP when you want to see the full Shodai agreement lifecycle work with a realistic agreement before authoring your own. You will run the service retainer example from authored agreement JSON through validation, deployment preflight, signed deployment, signed input submission, state reads, and input-history inspection. The service retainer is the teaching artifact for this tutorial. It is useful because it has participant roles, initialized business values, branching states, authorized inputs, EIP-712 signatures, state transitions, and an auditable history. You do not need to be building a retainer product to learn from it.

What you will learn

By the end of this workflow, you will have seen how:

authored agreement JSON defines variables, participants, states, inputs, issuers, and transitions
deployment context supplies live values such as participant wallets, chainId, and initialization data
deployment preflight normalizes the values that must be signed
EIP-712 permits authorize deployment and input submission
submitted inputs move an agreement through its authored state machine
state and input history provide receipts for what happened

Before you start

This tutorial has two equivalent paths. Use the MCP path when an agent is operating Shodai through MCP tools. Use the SDK path when you are building the workflow into a TypeScript integration.

Requirement	MCP path	SDK path
API access	An authenticated connection to the hosted MCP server.	A Shodai API key passed to `ApiClient`.
Example agreement	The `complex-example-agreement` MCP resource.	The complete JSON from Complex Agreement.
Environment	`environment: "testnet"` for this first run.	`new ApiClient({ environment: "testnet", apiKey })` for testnet.
Permit signer	An external signer that can sign returned EIP-712 typed data.	A `walletClient` that can sign with the intended account.

For setup details, see Quickstart with TypeScript SDK, Quickstart with MCP, TypeScript client reference, Authentication, and Complex Agreement.

Use testnet for a first run. Deployment and input submission are writes. They require signatures from eligible wallets, and successful submissions are not safe to retry blindly.

Run this workflow with an agent

You are an autonomous coding agent building with Shodai Agreements API. Start from the user's current context; if they already have a project, API key, agreement ID, error response, MCP tools, or clear task, skip generic onboarding and work from there.

First load documentation context:
1. Fetch https://docs.shodai.network/llms.txt and use it as the canonical page index.
2. Fetch https://docs.shodai.network/skill.md for agent workflow constraints.
3. Read the relevant page-level Markdown exports:
   - https://docs.shodai.network/integration-surfaces.md
   - https://docs.shodai.network/sdks/quickstart-with-typescript-sdk.md
   - https://docs.shodai.network/sdks/quickstart-with-mcp.md
   - https://docs.shodai.network/sdks/typescript-client.md
   - https://docs.shodai.network/authentication.md
   - https://docs.shodai.network/examples/complex.md
   - https://docs.shodai.network/workflow/validate-agreement-structure.md
   - https://docs.shodai.network/workflow/deploy-an-agreement.md
   - https://docs.shodai.network/workflow/operate-a-deployed-agreement.md
   - https://docs.shodai.network/reference/eip-712-signing.md
   - https://docs.shodai.network/reference/errors-and-troubleshooting.md
4. Fetch https://docs.shodai.network/openapi.json before composing raw routes, request bodies, response-status assertions, or payload schemas.
5. Use https://docs.shodai.network/llms-full.txt only as broad fallback context.

Choose the operating mode:
- Use MCP when MCP tools or MCP client context are available.
- Use the TypeScript SDK when building or testing a TypeScript integration.
- Do not force a temporary TypeScript project when operating through MCP.
- If no signing infrastructure exists and the user wants to continue past typed-data preparation, use the TypeScript SDK with viem as the local testnet signing harness.

Use complete docs examples, not abbreviated API reference snippets. Do not invent API routes, request bodies, agreement JSON, state IDs, input IDs, issuer rules, lifecycle behavior, nonce handling, or signing payloads.

Perform the workflow:
1. Confirm API or MCP authentication.
2. Load the complete service retainer agreement from https://docs.shodai.network/examples/complex.md or the complex-example-agreement MCP resource.
3. Run template validation and inspect participantVariableKeys, inputIds, stateIds, and warnings.
4. Prepare deployment context with testnet chain, participant wallet addresses, init values, and observers when needed.
5. Run deployment preflight before signing. Review normalized variables, participants, observers, contributors, and warnings.
6. Prepare or sign the deployment permit using the selected operating mode.
7. Deploy only when credentials, signing context, and user intent permit a live write.
8. Read the deployed agreement record and current state.
9. Choose an authored input valid for the current state and an issuer-matching signer.
10. Prepare or sign the input permit, then submit the input only when live writes are intended.
11. Reread state and input history. Verify the submitted input appears and report whether its status is PENDING, FINALIZED, or FAILED.
12. If blocked, troubleshoot from Shodai docs before asking the human, except for missing credentials, signing authority, or access.

Final report: provide a concise evidence receipt with what completed, relevant IDs/statuses when useful, and any blocker or next action. Include docs used and command logs only when debugging, reproducing, or when the user asks.

Choose a path

Both paths use the same lifecycle and the same underlying API model. The difference is the surface you operate through.

Lifecycle step	MCP tool	SDK method or helper
Validate authored JSON	`validate_agreement`	`client.validateTemplate(...)`
Preflight deployment	`preflight_deployment`	`client.validateDeployment(...)`
Prepare or create deploy permit	`prepare_deployment_typed_data`	`deployAgreementWithPermit(...)` or `signDeployWithPermit(...)`
Deploy with permit	`deploy_agreement`	`deployAgreementWithPermit(...)` or `client.deployWithPermit(...)`
Read current state	`get_agreement_state`	`client.getAgreementState(...)`
Prepare or create input permit	`prepare_input_typed_data`	`submitAgreementInputWithPermit(...)` or `signAgreementInputPermit(...)`
Submit signed input	`submit_input`	`submitAgreementInputWithPermit(...)` or `client.submitAgreementInput(...)`
Inspect input history	`get_input_history`	`client.listAgreementInputs(...)`

Run the workflow

Load the service retainer example

Read the complex-example-agreement MCP resource.The resource URI is:

agreements://examples/complex-agreement.json

MCP resources return JSON as text. Parse the returned contents[0].text value and keep the parsed object as agreement for the remaining MCP tool calls.This is the same agreement documented in Complex Agreement. It starts in AWAITING_PAYMENT, moves to WORK_IN_PROGRESS after initial payment proof, supports invoice review paths, can branch into top-up review, and can terminate through a final invoice flow.

Validate the authored agreement JSON

Call validate_agreement with environment: "testnet" and pass the parsed complex-example-agreement object as agreement.Review the validation result before continuing. The important evidence is the participant variable keys, state IDs, input IDs, and warnings. For this example, expect participant-backed variables such as serviceProviderRepresentative and clientRepresentative, and lifecycle inputs such as submitInitialPaymentProof and submitInvoice.Structural validation checks the agreement artifact only. It does not know which wallets or initialization values you will use for deployment.

Prepare deployment values

Choose deployment context for the first run.

Field	Example value	Why it matters
`chainId`	`59141`	Selects Linea Sepolia for a testnet deployment.
`displayName`	`Service Retainer Tutorial`	Names the hosted agreement record.
`serviceProviderRepresentative`	test wallet address	Authorizes service-provider inputs.
`clientRepresentative`	test wallet address	Authorizes client inputs.
`retainerTitle`	`Service Retainer Tutorial`	Initializes rendered agreement content.
`retainerDescription`	`A tutorial agreement used to learn the Shodai lifecycle.`	Initializes rendered agreement content.
`serviceProviderName`	`Provider LLC`	Initializes rendered agreement content.
`clientName`	`Client Inc`	Initializes rendered agreement content.
`retainerCeiling`	`1000`	Initializes business data used by the example.
`retainerFloor`	`200`	Initializes business data used by the example.
`paymentInstructions`	`Record payment proof using a testnet transaction or placeholder proof URL.`	Initializes rendered payment instructions.

Keep participant wallet mappings and initialization values stable after preflight. If they change, regenerate the deployment typed data before signing.

Preflight deployment

Call preflight_deployment with the loaded agreement object, target chain, initialization values, and participant mappings.Use this deployment context with the loaded agreement:

{
  "environment": "testnet",
  "chainId": 59141,
  "initValues": {
    "retainerTitle": "Service Retainer Tutorial",
    "retainerDescription": "A tutorial agreement used to learn the Shodai lifecycle.",
    "serviceProviderName": "Provider LLC",
    "clientName": "Client Inc",
    "retainerCeiling": 1000,
    "retainerFloor": 200,
    "paymentInstructions": "Record payment proof using a testnet transaction or placeholder proof URL."
  },
  "participants": [
    {
      "variableKey": "serviceProviderRepresentative",
      "walletAddress": "0x1111111111111111111111111111111111111111"
    },
    {
      "variableKey": "clientRepresentative",
      "walletAddress": "0x2222222222222222222222222222222222222222"
    }
  ]
}

Review the returned variables, participants, observers, contributors, and warnings before any signing step.

Preflight does not deploy the agreement. It assembles and validates the deployment request so you can sign the effective values rather than raw caller input.

Sign and deploy

For hosted MCP with external signing, call prepare_deployment_typed_data, sign the returned EIP-712 payload, then call deploy_agreement with the returned document link, normalized values, and permit fields.Call prepare_deployment_typed_data with:

environment: "testnet"
agreement: the loaded complex-example-agreement object
chainId: 59141
signerAddress: the wallet address that will sign and own the deployment
initValues: the same values used for preflight
participants: the same participant mappings used for preflight

prepare_deployment_typed_data
-> sign returned EIP-712 typed data externally
-> deploy_agreement

Pass the same agreement, displayName, and chainId; the returned docUri and documentId when present; the normalizedInitValues, normalizedParticipants, and normalizedObservers returned by prepare_deployment_typed_data; and signer address, deadline, and signature fields into deploy_agreement.

Do not sign one deployment payload and submit another. Agreement JSON, initialization values, participant mappings, docUri, chain, factory context, nonce, and deadline are all part of the authorization boundary.

Read the deployed state

After deployment, call get_agreement_state.

{
  "environment": "testnet",
  "agreementId": "<deployed agreement id>"
}

The service retainer starts at AWAITING_PAYMENT. The current state tells you which authored inputs can move the lifecycle next.

Submit the first lifecycle input

Submit submitInitialPaymentProof to move the retainer from AWAITING_PAYMENT to WORK_IN_PROGRESS.First call prepare_input_typed_data with an eligible signer and the input values.

{
  "environment": "testnet",
  "agreementId": "<deployed agreement id>",
  "inputId": "submitInitialPaymentProof",
  "values": {
    "awaitingPaymentPaymentLink": "https://sepolia.lineascan.build/tx/0xexample",
    "awaitingPaymentComment": "Initial payment proof recorded for the tutorial run."
  },
  "signerAddress": "0x2222222222222222222222222222222222222222"
}

Sign the returned EIP-712 typed data externally, then call submit_input with the same agreementId, inputId, values, signer address, deadline, and signature fields.The submitInitialPaymentProof input can be issued by either representative in the service retainer example. Later inputs may be restricted to one role.

Inspect state and history

Reread current state and input history.

get_agreement_state
get_input_history

Use state to confirm the lifecycle position and input history to confirm that the submitted input appears with its status. Depending on transaction timing, an input may be PENDING, FINALIZED, or FAILED.

Load the service retainer example

Save the canonical agreement JSON from Complex Agreement as service-retainer-agreement.json. Do not copy a shortened request body from the API reference or workflow pages.

import { readFile } from 'node:fs/promises';
import { ApiClient } from '@shodai-network/agreements-api-client';

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

const agreement = JSON.parse(
  await readFile(new URL('./service-retainer-agreement.json', import.meta.url), 'utf8'),
);

The SDK path also needs viem wallet and public clients when you deploy or submit inputs with permit helpers. Use a publicClient connected to the target agreement chain.

Validate the authored agreement JSON

Call client.validateTemplate(...) with the complete agreement.

const templateValidation = await client.validateTemplate(agreement);

console.log({
  participantVariableKeys: templateValidation.participantVariableKeys,
  inputIds: templateValidation.inputIds,
  stateIds: templateValidation.stateIds,
  warnings: templateValidation.warnings,
});

Template validation checks the authored agreement artifact. It does not include deployment-specific values such as chainId, participant wallet mappings, observers, or initialization values.

Prepare deployment values

Create test-only wallets for the participant roles, then prepare initialization values and participant mappings.

import { createPublicClient, createWalletClient, http } from 'viem';
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
import { lineaSepolia } from 'viem/chains';

const chainId = 59141;
const serviceProvider = privateKeyToAccount(generatePrivateKey());
const clientRepresentative = privateKeyToAccount(generatePrivateKey());

const publicClient = createPublicClient({
  chain: lineaSepolia,
  transport: http(process.env.RPC_URL),
});

const walletClient = createWalletClient({
  account: serviceProvider,
  chain: lineaSepolia,
  transport: http(process.env.RPC_URL),
});

const initValues = {
  retainerTitle: 'Service Retainer Tutorial',
  retainerDescription: 'A tutorial agreement used to learn the Shodai lifecycle.',
  serviceProviderName: 'Provider LLC',
  clientName: 'Client Inc',
  retainerCeiling: 1000,
  retainerFloor: 200,
  paymentInstructions: 'Record payment proof using a testnet transaction or placeholder proof URL.',
};

const participants = [
  {
    variableKey: 'serviceProviderRepresentative',
    walletAddress: serviceProvider.address,
  },
  {
    variableKey: 'clientRepresentative',
    walletAddress: clientRepresentative.address,
  },
];

These mappings record the live participant addresses; they do not link either wallet to a Shodai account. An account that later proves control of an assigned address can discover the agreement through that wallet without an invitation step. See Link Wallets and Access Agreements.Use generated wallets only for local tests and tutorials. Do not persist or commit generated private keys.

Preflight deployment

Call client.validateDeployment(...) before requesting a signature.

const deploymentValidation = await client.validateDeployment({
  agreement,
  chainId,
  initValues,
  participants,
});

console.log({
  variables: deploymentValidation.variables,
  participants: deploymentValidation.participants,
  observers: deploymentValidation.observers,
  contributors: deploymentValidation.contributors,
  warnings: deploymentValidation.warnings,
});

Use deploymentValidation.variables as the effective deployment values that the SDK will sign. Keep the same participants array in the deploy helper so hosted agreement context records the participant mappings.

Sign and deploy

Use the high-level helper for the normal TypeScript path.

import { deployAgreementWithPermit } from '@shodai-network/agreements-api-client';

const agreementRecord = await deployAgreementWithPermit({
  client,
  walletClient,
  publicClient,
  chainId,
  agreement,
  displayName: 'Service Retainer Tutorial',
  initValues: deploymentValidation.variables,
  participants,
});

The helper resolves chain-specific factory context, reads the current permit nonce, signs the deployment permit, and submits the deployment request. If the agreement JSON, initialization values, participant mappings, chain, nonce, or deadline change, regenerate the signature.

Read the deployed state

Read the hosted agreement record and current state.

const deployed = await client.getAgreement(agreementRecord.id);
const currentState = await client.getAgreementState(agreementRecord.id);

console.log({
  id: deployed.id,
  address: deployed.address,
  chainId: deployed.chainId,
  state: currentState.state,
});

The service retainer starts at AWAITING_PAYMENT. Use the current state with the authored agreement JSON to decide which input is valid next.

Submit the first lifecycle input

Submit submitInitialPaymentProof to move the retainer from AWAITING_PAYMENT to WORK_IN_PROGRESS.

import { submitAgreementInputWithPermit } from '@shodai-network/agreements-api-client';

const clientWallet = createWalletClient({
  account: clientRepresentative,
  chain: lineaSepolia,
  transport: http(process.env.RPC_URL),
});

const inputRecord = await submitAgreementInputWithPermit({
  client,
  agreementId: agreementRecord.id,
  walletClient: clientWallet,
  publicClient,
  chainId: agreementRecord.chainId,
  agreementContractAddress: agreementRecord.address!,
  agreement,
  inputId: 'submitInitialPaymentProof',
  values: {
    awaitingPaymentPaymentLink: 'https://sepolia.lineascan.build/tx/0xexample',
    awaitingPaymentComment: 'Initial payment proof recorded for the tutorial run.',
  },
});

console.log(inputRecord.status);

The signer must be allowed by the input’s authored issuer. The service retainer allows either representative to submit initial payment proof, but later inputs may be restricted to one role.

Inspect state and history

Reread state and input history after submission.

const nextState = await client.getAgreementState(agreementRecord.id);
const inputsPage = await client.listAgreementInputs(agreementRecord.id, {
  limit: 25,
});

console.log({
  state: nextState.state,
  inputs: inputsPage.data.map((input) => ({
    inputId: input.inputId,
    status: input.status,
    createdAt: input.createdAt,
  })),
});

Use state for the agreement’s current lifecycle position and input history as the audit trail of submitted events.

Try a branch

After the agreement reaches WORK_IN_PROGRESS, try one additional path to see why the complex example is useful.

Submit an invoice without a top-up request

Submit the submitInvoice input from WORK_IN_PROGRESS. The service provider representative must sign this input.Required values:

{
  "retainerBalanceBeforeInvoice": 1000,
  "invoiceLineItems": "2026-04-01,Advisory services,10,100,1000",
  "submitInvoiceComment": "Invoice submitted for April services."
}

This path moves the agreement to INVOICE_SUBMITTED. From there, an authorized representative can approve, reject with feedback, or initiate termination.

Submit an invoice with a top-up request

Submit the submitInvoiceWithTopup input from WORK_IN_PROGRESS. The service provider representative must sign this input.Required values:

{
  "retainerBalanceBeforeInvoice": 300,
  "invoiceLineItems": "2026-04-01,Advisory services,10,100,1000",
  "topupInvoiceComment": "Invoice submitted with top-up request."
}

This path moves the agreement to INVOICE_SUBMITTED_WITH_TOPUP. The next step can approve with payment proof, reject with feedback, or initiate termination.

What happened under the hood

This tutorial uses one concrete agreement to exercise the core Shodai model.

Tutorial action	System concept	Where to learn more
Load the service retainer JSON	Agreement JSON defines the readable content and executable lifecycle.	Agreement data standard
Validate template	Structural validation checks authored variables, states, inputs, issuers, and transitions.	Validate Agreement Structure
Add participant wallets and `initValues`	Deployment context binds the reusable agreement template to live parties and values.	Deploy an Agreement
Link a participant wallet to an account	Wallet control becomes an account-level identity signal for agreement discovery.	Link Wallets and Access Agreements
Preflight before signing	Preflight normalizes effective values and catches deployment issues before authorization.	Deploy an Agreement
Sign deployment and input permits	EIP-712 signatures prove that an eligible wallet authorized the write.	EIP-712 Signing Reference
Submit `submitInitialPaymentProof`	Inputs are signed lifecycle events accepted only from allowed issuers.	Author Agreement JSON
Reread state and input history	State shows the current lifecycle position; history shows the submitted event trail.	Operate a Deployed Agreement

If a step fails

Use Errors and troubleshooting for API errors, signing failures, and lifecycle diagnostics. Before retrying a write, reread state and input history so you do not sign or submit against a stale lifecycle position.

Next steps

Inspect the complex agreement

Study the complete service retainer JSON, lifecycle diagram, states, inputs, and transitions.

Author your own agreement

Turn a business workflow into agreement JSON after you have run the lifecycle once.

Build with the SDK

Use the TypeScript client reference for typed API calls, signing helpers, and diagnostics.

Quickstart with MCP

Configure the hosted MCP server and operate agreements through MCP tools.

Start

Workflow

Webhooks

Architecture

Examples

Reference

What you will learn

Before you start

Choose a path

Run the workflow

Try a branch

What happened under the hood

If a step fails

Next steps

Inspect the complex agreement

Author your own agreement

Build with the SDK

Quickstart with MCP

​What you will learn

​Before you start

​Choose a path

​Run the workflow

​Try a branch

​What happened under the hood

​If a step fails

​Next steps

Inspect the complex agreement

Author your own agreement

Build with the SDK

Quickstart with MCP

What you will learn

Before you start

Choose a path

Run the workflow

Try a branch

What happened under the hood

If a step fails

Next steps