Shodai Reference App

The Shodai Reference App is the canonical full-stack example for building a customer-owned application on the Agreements API. It shows how an app can combine its own frontend, backend, auth, storage, template catalog, wallet signing, Agreements API calls, and webhook reconciliation without exposing Shodai API keys or webhook secrets to the browser. Use it when you want to understand the shape of a production-style integration before adapting the patterns to your own stack.

When to use this example

Use this page to understand the full-stack integration model behind the Reference App. Use the SDK repository docs when you are ready to run it locally, configure third-party services, or deploy it. For agreement JSON examples, start with Simple Agreement or Complex Agreement. For focused API workflows, use Deploy an Agreement, Operate a Deployed Agreement, Receive webhooks, Agreement activity webhooks, and Notification webhooks.

What the app demonstrates

Pattern	What to look for
Full-stack Agreements API lifecycle	Template selection, draft creation, participant and observer setup, deployment, state viewing, action submission, and activity history.
Customer-owned boundary	The frontend talks to its own backend. The backend talks to Shodai.
Server-side secrets	The Nest backend owns the Shodai API key, webhook secret, Dynamic server token, service token, and Mongo credentials.
Wallet signing	The browser signs deploy and input permits with the connected wallet, then sends signed payloads to the backend.
Local persistence	The app owns users, contacts, wallets, template access, drafts, agreement mirrors, input mirrors, and webhook event records in Mongo.
Reconciliation	After writes and webhook deliveries, the backend reads canonical agreement state and input history from the Agreements API.

Architecture at a glance

Layer	What it owns
React frontend at `/agreements/`	Authenticated product workflow, agreement creation UX, document and state views, and wallet signing for deploy and input permits.
Nest backend	Auth validation, app-owned API routes, Shodai API key, webhook secret, agreement lifecycle orchestration, and local persistence.
Mongo	App-owned users, contacts, wallets, template access, drafts, agreement mirrors, input mirrors, webhook receipts, and processing state.
Shodai Agreements API	Canonical deployed agreement records, state, accepted input history, deployment and input processing, and webhook delivery.

The app runs independently of internal Shodai services. In local development, the backend defaults to http://localhost:4199 and the frontend defaults to http://localhost:5184/agreements/.

Agreement lifecycle in the app

The Reference App models the complete customer application path around the Agreements API:

A user signs in through the app’s auth flow.
The backend mirrors the platform user, contacts, and wallets locally.
The frontend loads available agreement templates from the backend.
The backend resolves a selected templateId against its vendored template catalog.
The user configures draft values, participants, observers, display name, and chain.
The browser signs an EIP-712 deploy permit with the connected wallet.
The backend validates the signer and deploys through the Agreements API using @shodai-network/agreements-api-client.
The deployed agreement view reads agreement details, state, and inputs through the backend.
When an action is available, the browser signs an input permit.
The backend submits the input to the Agreements API and refreshes its local mirror.
Agreement activity webhooks notify the backend about Shodai-side transitions, and the backend reconciles by reading current data from the Agreements API.
Notification webhooks notify the backend when hosted Shodai notification rules fire, and the backend owns final delivery such as SES email.

App-owned data and Shodai-owned data

App-owned locally	Shodai-owned canonically
Platform user mirror, contacts, wallets, and auth-adjacent records.	Deployed agreement records.
Template access and the vendored template catalog.	Canonical agreement state.
Draft agreements before deployment.	Accepted input history.
Display names and UX-specific metadata.	Agreement deployment and transition outcomes.
Local agreement and input mirrors.	Signed webhook deliveries.
Webhook event receipts, queue status, retry metadata, and dead-letter metadata.	Webhook event payload source.

The app may cache and mirror deployed agreement data, but Shodai remains the source of truth for deployed agreement state and accepted inputs.

Security boundary

Do not place Shodai API keys or webhook secrets in frontend code or VITE_ environment variables.

Keep EXTERNAL_API_KEY, SHODAI_WEBHOOK_SECRET, Dynamic server tokens, service tokens, and Mongo credentials on the backend. The frontend should only receive browser-safe configuration such as its own backend URL, Dynamic environment ID, supported chains, and RPC configuration.

Webhook reconciliation in context

The webhook receiver is POST /shodai/webhooks. For hosted webhook testing against local development, expose backend port 4199 through a public HTTPS tunnel and register the tunnel URL with Shodai. Webhooks are compact events, not full agreement snapshots. The backend verifies, stores, acknowledges, and processes deliveries. Agreement activity webhooks reconcile the local agreement mirror by reading current agreement data from the Agreements API. Notification webhooks trigger final app-owned delivery, such as sending email through SES. For the shared receiver pattern, see Receive webhooks. For event-specific behavior, see Agreement activity webhooks and Notification webhooks.

What you can replace

The Reference App is a blueprint, not a required stack.

Customers are not required to use Dynamic, Mongo, Nest, React, the vendored template catalog model, or the exact local storage schema. The reusable patterns are:

keep Shodai credentials server-side
put a customer-owned backend between the browser and the Agreements API
let wallets sign deploy and input permits in the browser
submit signed payloads through a trusted backend
maintain local product state separately from Shodai-owned canonical agreement state
reconcile local mirrors from Agreements API reads and webhook deliveries

Run or inspect the app

Use the SDK repository for setup and deployment details:

Repo path	Use it for
`apps/shodai-reference-app`	Reference App source.
`apps/shodai-reference-app/README.md`	App overview, local requirements, runtime defaults, validation commands, and webhook testing notes.
`apps/shodai-reference-app/docs/third-party-setup.md`	Local setup details for Dynamic, Shodai API keys, webhook subscriptions, RPC, environment files, Mongo, and validation.
`apps/shodai-reference-app/docs/deployment.md`	Production-style serving, proxy routes, frontend build path, backend environment, and deployment validation.

The app lives at apps/shodai-reference-app in the SDK repo. The frontend is served at /agreements/. Local development defaults are backend http://localhost:4199 and frontend http://localhost:5184/agreements/. Webhook testing against hosted Shodai requires a public HTTPS tunnel to backend port 4199.

For webhook endpoint request and response schemas, use the Webhooks pages in the API Reference group.

Start

Workflow

Webhooks

Architecture

Examples

Reference

When to use this example

What the app demonstrates

Architecture at a glance

Agreement lifecycle in the app

App-owned data and Shodai-owned data

Security boundary

Webhook reconciliation in context

What you can replace

Run or inspect the app

​When to use this example

​What the app demonstrates

​Architecture at a glance

​Agreement lifecycle in the app

​App-owned data and Shodai-owned data

​Security boundary

​Webhook reconciliation in context

​What you can replace

​Run or inspect the app

​Related pages

When to use this example

What the app demonstrates

Architecture at a glance

Agreement lifecycle in the app

App-owned data and Shodai-owned data

Security boundary

Webhook reconciliation in context

What you can replace

Run or inspect the app

Related pages