TypeScript client reference

Use Quickstart with TypeScript SDK for first setup. Use this page after connection to choose client methods, signing helpers, diagnostics, path helpers, and exports. MCP users who do not already have a wallet or signing service can also use this page to set up the TypeScript SDK with viem as a local testnet signing harness for typed data prepared by Quickstart with MCP. Use literal SDK symbols exactly as exported by the package, including ApiClient, AgreementsApiError, agreementsApiPaths, and API_BASE_PATH. The package targets Node >=18.

Install

npm install @shodai-network/agreements-api-client viem

@shodai-network/agreements-protocol-evm is installed automatically as a package dependency. Install viem in your app when you use permit-signing helpers. The Agreements API client and the onchain protocol SDK are both published under the @shodai-network npm organization. The agreements-api-playground sample application uses @shodai-network/agreements-api-client for API calls and @shodai-network/agreements-protocol-evm for onchain agreement typing and signing support.

Create a client

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

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

const health = await client.getHealth();

Constructor config:

Field	Use
`environment`	Named API environment. Supported values are `testnet` and `production`.
`baseUrl`	Optional API host base URL override, without `/v0` appended. Use for local proxies, staging hosts, or custom deployments.
`apiKey`	Optional `X-API-Key` value. Most API methods require it.
`tokenProvider`	Optional bearer-token provider called before each request. Use it instead of `apiKey`.
`headers`	Optional header record or header factory merged into each request.
`fetch`	Optional fetch implementation. Defaults to `globalThis.fetch`.

If both environment and baseUrl are supplied, baseUrl wins. testnet resolves to https://test-api.shodai.network; production resolves to https://api.shodai.network. apiKey and tokenProvider are mutually exclusive. For a user-delegated provider in an installed Node.js client, follow Connect an installed TypeScript client with delegated OAuth. For key provisioning, scopes, entitlements, and 401/402/403 behavior, see Authentication.

Wallet and RPC requirements

The API key authenticates requests. Deploying agreements and submitting agreement inputs also require a wallet your integration controls because those workflows depend on EIP-712 signatures.

Requirement	Why it matters
`walletClient`	Controls the signing account and produces EIP-712 signatures. A plain wallet address is not enough.
`publicClient`	Reads target-chain context, factory or agreement contract state, and current permit nonces.
Target chain/RPC	Must match the selected deployment chain or the deployed agreement’s chain.
Signer eligibility	For inputs, the signing wallet must be allowed by the authored input `issuer`.

Create a test-only wallet client

For automated tests that only need EIP-712 signatures, create an ephemeral wallet with viem. This wallet does not need gas when it only signs permits. Do not use this pattern for production wallets, and do not commit generated private keys.

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

const account = privateKeyToAccount(generatePrivateKey());

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

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

The testnet API environment supports Linea Sepolia (59141), Ethereum Sepolia (11155111), and Base Sepolia (84532) for agreement deployments. The production API environment supports Linea Mainnet (59144) and Base Mainnet (8453). Choose the chainId explicitly for deployment preflight and deploy requests, then reuse the deployed agreement record’s chainId when signing inputs. Use account.address in participant mappings when the test wallet needs to deploy an agreement or submit an input for a participant role. Before calling deployAgreementWithPermit(...) or submitAgreementInputWithPermit(...), confirm that:

you have an API key for authenticated requests
you have a walletClient that can sign with the intended account
you have a publicClient connected to the target chain
the wallet chain matches the deployment or agreement chain
the signer is appropriate for the deployment or input issuer
you can regenerate signatures when nonce, deadline, payload, chain, agreement JSON, or values change

Choose the right SDK surface

Use case	Prefer
Normal API calls	`ApiClient` methods such as `validateTemplate`, `validateDeployment`, and `getAgreementState`.
Deploy with an EIP-712 permit	`deployAgreementWithPermit(...)`.
Submit a signed input	`submitAgreementInputWithPermit(...)`.
Sign first, submit later, or customize request composition	`signDeployWithPermit(...)` or `signAgreementInputPermit(...)` plus `client.deployWithPermit(...)` or `client.submitAgreementInput(...)`.
Debug HTTP status, headers, or raw body text	`client.exchangeJson(...)`.
Compose a raw request path safely	`agreementsApiPaths`.
Construct typed data manually without SDK helpers	EIP-712 Signing Reference.

Main client methods

The public API returns JSON envelopes for authenticated agreement routes. SDK methods that read one resource unwrap data and return the resource directly. List methods return the list envelope so your integration can read data, pageInfo, and meta.

const agreement = await client.getAgreement(agreementId);

const page = await client.listAgreements({ limit: 25 });
console.log(page.data, page.pageInfo.nextCursor, page.meta.requestId);

Method	Use
`getOpenApiDocument()`	Fetch `GET /v0/openapi.json`.
`getHealth()`	Check `GET /v0/health`.
`createWebhook(body)`	Register a signed webhook endpoint. Returns the signing secret once.
`listWebhooks()`	List webhook subscriptions for the API principal.
`getWebhook(webhookId)`	Read one webhook subscription.
`updateWebhook(webhookId, body)`	Update a webhook URL, filters, event types, or status.
`deleteWebhook(webhookId)`	Disable a webhook subscription.
`testWebhook(webhookId)`	Send a signed test payload to the subscription URL.
`listAgreements(params)`	List paged agreement summaries visible to the API key. Supports `limit`, `cursor`, `sort`, `chainId`, `state`, and created/updated date filters.
`getAgreement(agreementId)`	Read one agreement record.
`getAgreementDocument(documentId)`	Read a generated agreement document through `GET /v0/agreements/documents/{documentId}`.
`validateTemplate(agreement)`	Validate authored agreement JSON with `POST /v0/agreements/validate-template`.
`validateDeployment(body)`	Preflight deployment context with `POST /v0/agreements/validate`.
`deployWithPermit(body)`	Deploy with a prepared EIP-712 permit.
`getAgreementState(agreementId)`	Read the current agreement state.
`listAgreementInputs(agreementId, params)`	Read paged input history. Supports `limit`, `cursor`, `sort`, `userId`, `inputId`, `status`, and created/updated date filters.
`submitAgreementInput(agreementId, body)`	Submit a signed input.
`exchangeJson(method, path, body?)`	Inspect raw response metadata without throwing for HTTP errors.
`request<T>(method, path, body?, okStatus?)`	Low-level JSON request that returns the raw JSON body and throws on unexpected status.

List filters use qs-style bracket modifiers. For example, { createdAt: { gte: '...' }, sort: { createdAt: 'desc' } } serializes as createdAt[gte]=...&sort[createdAt]=desc. Agreement lists support chainId, state, createdAt, updatedAt, limit, cursor, and one sort field from createdAt, updatedAt, or displayName. Input history supports userId, inputId, status, createdAt, updatedAt, limit, cursor, and one sort field from createdAt or updatedAt. Date filters support gt, gte, lt, and lte; limit must be between 1 and 100.

const agreementsPage = await client.listAgreements({
  chainId: 59141,
  state: 'AWAITING_PAYMENT',
  createdAt: { gte: '2026-05-01T00:00:00.000Z' },
  sort: { createdAt: 'desc' },
  limit: 25,
});
const nextAgreementPage = agreementsPage.pageInfo.nextCursor
  ? await client.listAgreements({ cursor: agreementsPage.pageInfo.nextCursor, limit: 25 })
  : null;

const inputsPage = await client.listAgreementInputs('agreement-123', {
  userId: 'platform-user-id',
  status: 'FINALIZED',
  updatedAt: { lt: '2026-06-01T00:00:00.000Z' },
  sort: { updatedAt: 'asc' },
  limit: 25,
});

Receive webhook events

Use webhooks when your integration should react to agreement activity or notification rules without polling agreement state. Webhook subscriptions can receive agreement.transitioned and agreement.notification.triggered events for agreement records associated with the current API principal. For signing, retries, filters, and delivery behavior, see Receive webhooks. For event-family details, see Agreement activity webhooks and Notification webhooks.

const created = await client.createWebhook({
  url: 'https://example.com/shodai/webhooks',
  eventTypes: ['agreement.transitioned', 'agreement.notification.triggered'],
  filters: {
    templateIds: ['did:template:service-retainer-v0-1'],
  },
});

console.log(created.id);
console.log(created.secret);

Store created.secret immediately. It is returned only when the webhook is created. listWebhooks, getWebhook, updateWebhook, deleteWebhook, and testWebhook do not return the signing secret. To receive agreement.notification.triggered, include an external_webhook notification template when you deploy the agreement. The API scopes that template to the authenticated principal and deployed agreement. See Notification webhooks for supported triggers, temporal rules, recipients, interpolation, and payloads.

await client.deployWithPermit({
  agreement,
  displayName: 'Consulting Agreement',
  chainId: 59141,
  signer,
  deadline,
  signature,
  notificationTemplate: {
    rules: [
      {
        id: 'deployment-follow-up',
        name: 'Deployment follow-up',
        trigger: { type: 'onTransition', inputs: ['__deploy'] },
        recipients: ['@observers'],
        notification: {
          channel: 'external_webhook',
          subject: 'Agreement deployed',
          body: 'Agreement ${agreementId} is ready for review.',
        },
      },
    ],
  },
});

Use constructWebhookEvent(...) from the webhook helper export to verify signed deliveries against the exact raw request body:

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

const event = constructWebhookEvent(
  rawBody,
  headers,
  process.env.SHODAI_WEBHOOK_SECRET!,
);

const subscriptions = await client.listWebhooks();
await client.testWebhook(subscriptions.data[0].id);

Use deleteWebhook(webhookId) to disable a subscription. The API returns the disabled subscription; it does not hard-delete the subscription record.

Validate and deploy with helpers

Use deployment preflight before signing when initValues, participant mappings, or observers affect the deployment request.

const chainId = 59141;

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

console.log(validation.variables);

Then use the high-level helper for the normal sign-and-submit path.

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

const agreementRecord = await deployAgreementWithPermit({
  client,
  walletClient,
  publicClient,
  chainId,
  agreement,
  displayName: 'Consulting Agreement',
  initValues: validation.variables,
  participants,
  observers,
});

Participant-derived values in validation.variables are the effective values the SDK signs for deployment. Keep the same participants array in deployAgreementWithPermit(...) so hosted agreement context records the participant mappings.

When neither docUri nor permitOptions.docUri is supplied, deployAgreementWithPermit(...) generates a documentId and signs a docUri that points at GET /v0/agreements/documents/{documentId}. Pass docUri or documentId explicitly when your integration owns document addressing.

Submit signed inputs with helpers

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

await submitAgreementInputWithPermit({
  client,
  agreementId: agreementRecord.id,
  walletClient,
  publicClient,
  chainId: agreementRecord.chainId,
  agreementContractAddress,
  agreement,
  inputId: 'partyASignature',
  values,
});

publicClient must be connected to the target chain/RPC. Input submissions also require chainId from the deployed agreement record so the helper can fail before signing if the client is connected to the wrong chain. The signing helpers use publicClient to resolve the chain-specific AgreementFactory or agreement contract context and to read the current permit nonce before signing.

Control deadlines and low-level signing

import {
  computeDefaultDeadlineSeconds,
  signAgreementInputPermit,
  signDeployWithPermit,
} from '@shodai-network/agreements-api-client';

DEFAULT_PERMIT_DEADLINE_SECONDS is 3600. computeDefaultDeadlineSeconds(offsetSeconds = 3600) returns the current Unix time plus the offset. High-level deployAgreementWithPermit(...) and submitAgreementInputWithPermit(...) default the deadline. Low-level signDeployWithPermit(...) and signAgreementInputPermit(...) require an explicit deadline. Use low-level signing helpers when your application needs to sign first and submit later, inspect the signature, or compose the request body itself. Use EIP-712 Signing Reference only when you need to construct the typed data directly or debug helper behavior.

Handle API errors

The client throws AgreementsApiError when the response status does not match the expected success status.

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

try {
  await client.listAgreements();
} catch (error) {
  if (error instanceof AgreementsApiError) {
    console.error(error.status, error.errorPayload?.error.message ?? error.bodyText);
  }
  throw error;
}

AgreementsApiError exposes status, bodyText, parsedBody, and errorPayload. errorPayload.error.code is stable for branching, and errorPayload.error.requestId is the value to share when you need support to trace a request.

Use raw exchange for diagnostics

Use exchangeJson() when you need response metadata or raw body text during debugging. It does not throw for HTTP error status codes.

const response = await client.exchangeJson('GET', '/v0/agreements');

console.log(response.status, response.ok, response.parsedBody);

exchangeJson() accepts DELETE, GET, PATCH, and POST. It returns status, ok, headers, bodyText, and parsedBody.

Use path helpers when composing raw calls

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

const path = agreementsApiPaths.agreementState('agreement-123');

Path helper names are openapiJson, health, webhooks, webhook, webhookTest, agreements, agreementsValidate, agreementsValidateTemplate, agreementsDeployWithPermit, agreementDocument, agreement, agreementState, agreementInputs, and agreementInput. ID path helpers encode IDs and use API_BASE_PATH, which is /v0.

Root exports

The package root exports these values, classes, and functions:

ApiClient
AgreementsApiError
extractAgreementsApiErrorMessage
agreementsApiPaths
getExecutionInputIds
joinUrl
API_BASE_PATH
API_ENVIRONMENT_BASE_URLS
API_MAJOR_VERSION
DEFAULT_API_ENVIRONMENT
resolveApiBaseUrl
buildAgreementDocumentUri
createAgreementDocumentId
computeDefaultDeadlineSeconds
DEFAULT_PERMIT_DEADLINE_SECONDS
signDeployWithPermit
signAgreementInputPermit
deployAgreementWithPermit
submitAgreementInputWithPermit

The package root exports these TypeScript types:

AgreementInputRecord
AgreementDocumentResponse
AgreementInputListParams
AgreementInputListSortField
AgreementListParams
AgreementListSortField
AgreementRecord
AgreementSummary
AgreementStateResponse
ApiResponse
DateFilter
DirectDeployAgreementWithPermitRequest
ErrorResponse
HealthResponse
ListResponse
NotificationRule
NotificationTemplate
PageInfo
ParticipantRecord
ApiClientConfig
AgreementsApiEnvironment
CreateWebhookRequest
CreateWebhookResponse
DirectParticipantRecord
PermitSignature
ProcessInputRequest
SortDirection
SortFilter
UpdateWebhookRequest
ValidateDirectAgreementRequest
ValidateDirectAgreementResponse
ValidateDirectAgreementTemplateResponse
WebhookEventType
WebhookFilters
WebhookSubscriptionEventType
WebhookSubscription
WebhookSubscriptionStatus
WebhookTestResponse
DeployWithPermitCallParams
SignDeployPermitParams
SignDeployPermitResult
SignInputPermitParams
SignInputPermitResult
SubmitInputCallParams

The @shodai-network/agreements-api-client/client export provides ApiClient. The @shodai-network/agreements-api-client/webhooks export provides webhook receiver helpers and types:

constructWebhookEvent
verifyWebhookSignature
computeWebhookSignature
WebhookVerificationError
WebhookVerificationErrorCode
WebhookRawBody
WebhookHeaders
WebhookEventType
WebhookEventEnvelope
WebhookTestData
WebhookTestEvent
AgreementTransitionedWebhookData
AgreementTransitionedWebhookEvent
NotificationAttachmentStrategy
AgreementNotificationTriggeredWebhookData
AgreementNotificationTriggeredWebhookEvent
UnknownWebhookEvent
ShodaiWebhookEvent
VerifiedWebhookMetadata
ConstructWebhookEventOptions
WEBHOOK_ID_HEADER
WEBHOOK_TIMESTAMP_HEADER
WEBHOOK_SIGNATURE_HEADER
DEFAULT_WEBHOOK_TOLERANCE_SECONDS
WEBHOOK_API_VERSION

The Node-only @shodai-network/agreements-api-client/oauth export provides these delegated OAuth symbols used by the installed-client guide:

OauthDelegatedSession
OauthDelegatedTokenSet

Start

Workflow

Webhooks

Architecture

Examples

Reference

Install

Create a client

Wallet and RPC requirements

Create a test-only wallet client

Choose the right SDK surface

Main client methods

Receive webhook events

Validate and deploy with helpers

Submit signed inputs with helpers

Control deadlines and low-level signing

Handle API errors

Use raw exchange for diagnostics

Use path helpers when composing raw calls

Root exports

​Install

​Create a client

​Wallet and RPC requirements

​Create a test-only wallet client

​Choose the right SDK surface

​Main client methods

​Receive webhook events

​Validate and deploy with helpers

​Submit signed inputs with helpers

​Control deadlines and low-level signing

​Handle API errors

​Use raw exchange for diagnostics

​Use path helpers when composing raw calls

​Root exports

​Related pages

Install

Create a client

Wallet and RPC requirements

Create a test-only wallet client

Choose the right SDK surface

Main client methods

Receive webhook events

Validate and deploy with helpers

Submit signed inputs with helpers

Control deadlines and low-level signing

Handle API errors

Use raw exchange for diagnostics

Use path helpers when composing raw calls

Root exports

Related pages