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. |
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
@cns-labs/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. |
Security boundary
Do not place Shodai API keys or webhook secrets in frontend code or VITE_ environment variables.
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.
- 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. |
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.
Related pages
For webhook endpoint request and response schemas, use the Webhooks pages in the API Reference group. 
