Agreements API SDK

Open-source home for the TypeScript client for the Agreements API and the reference playground app built on top of it.

Install the SDK

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

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

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

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

What This Repository Contains

• packages/agreements-api-client: publishable npm package @cns-labs/agreements-api-client
• apps/agreements-api-playground: reference Vite app for validating agreements, deploying with permits, inspecting state, and submitting inputs

Start Here

• SDK usage and API lifecycle docs: packages/agreements-api-client/README.md
• Reference implementation and local browser workflow: apps/agreements-api-playground/README.md
• Full end-to-end example UI: apps/agreements-api-playground/src/App.tsx

Agreements API Environments

The SDK now 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

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

# from the repository root
pnpm install
pnpm build
pnpm dev:playground

The playground defaults to http://localhost:5176.

If that port is already in use, start the playground on another port:

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.

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

Open Source Project Notes

• Package metadata and consumer-facing README live under packages/agreements-api-client.
• Maintainer workflows live in packages/agreements-api-client/DEVELOPMENT.md.
• License: Apache-2.0