{
"openapi": "3.1.0",
"info": {
"title": "Agreements API",
"version": "v0",
"description": "Author, deploy, read, and advance agreements through the Agreements API."
},
"servers": [
{
"url": "https://test-api.shodai.network",
"description": "Public base URL for the Agreements API testnet environment."
},
{
"url": "https://api.shodai.network",
"description": "Public base URL for the Agreements API production environment."
}
],
"tags": [
{
"name": "Agreement Records",
"description": "List and read agreement records."
},
{
"name": "Agreement Documents",
"description": "Resolve hosted agreement prose documents."
},
{
"name": "Authoring",
"description": "Check authored agreement JSON before deployment."
},
{
"name": "Deployment",
"description": "Preflight and deploy agreements."
},
{
"name": "Using Agreements",
"description": "Read state, inspect input history, and submit signed inputs."
},
{
"name": "Webhooks",
"description": "Register signed push callbacks for agreement events."
},
{
"name": "System",
"description": "Health and OpenAPI discovery endpoints."
}
],
"paths": {
"/v0/openapi.json": {
"get": {
"summary": "Get the OpenAPI document for the Agreements API",
"description": "Returns the OpenAPI 3.1 specification describing the Agreements API surface.",
"tags": [
"System"
],
"responses": {
"200": {
"description": "OpenAPI document for the Agreements API.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"operationId": "getExternalApiOpenApiDocument",
"x-mint": {
"metadata": {
"sidebarTitle": "Get OpenAPI document"
}
}
}
},
"/v0/health": {
"get": {
"summary": "Health check",
"description": "Public health endpoint for the API gateway.",
"tags": [
"System"
],
"responses": {
"200": {
"description": "Gateway health payload.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthResponse"
},
"examples": {
"ok": {
"summary": "Gateway is healthy",
"value": {
"status": "ok",
"service": "external-api",
"timestamp": "2026-04-27T16:00:00.000Z"
}
}
}
}
}
}
},
"operationId": "getExternalApiHealth",
"x-mint": {
"metadata": {
"sidebarTitle": "Health check"
}
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "import { ApiClient } from '@shodai-network/agreements-api-client';\n\nconst client = new ApiClient({ baseUrl: process.env.BASE_URL! });\nconst health = await client.getHealth();"
}
]
}
},
"/v0/webhooks": {
"post": {
"summary": "Create webhook",
"description": "Registers a signed webhook endpoint for subscribed agreement activity and notification events visible to the current API principal. The signing secret is returned only in the create response.",
"tags": [
"Webhooks"
],
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
},
"examples": {
"webhook": {
"summary": "Webhook registration",
"value": {
"url": "https://example.com/shodai/webhooks",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created webhook subscription.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/CreateWebhookResponse"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"created": {
"summary": "Created webhook subscription with one-time signing secret",
"value": {
"data": {
"id": "wh_123",
"principalId": "principal_123",
"url": "https://example.com/shodai/webhooks",
"status": "active",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
},
"createdAt": "2026-05-26T16:00:00.000Z",
"updatedAt": "2026-05-26T16:00:00.000Z",
"secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"400": {
"description": "Invalid webhook registration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "createWebhook",
"x-mint": {
"metadata": {
"sidebarTitle": "Create webhook"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nCreate a signed webhook endpoint for agreement activity and notification events. The signing secret is returned only in the create response."
}
},
"get": {
"summary": "List webhooks",
"description": "Lists webhook subscriptions for the current API principal. Signing secrets are not returned after creation.",
"tags": [
"Webhooks"
],
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Webhook subscriptions.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"pageInfo",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookSubscription"
}
},
"pageInfo": {
"$ref": "#/components/schemas/PageInfo"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"webhooks": {
"summary": "Webhook subscriptions for the current API principal",
"value": {
"data": [
{
"id": "wh_123",
"principalId": "principal_123",
"url": "https://example.com/shodai/webhooks",
"status": "active",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
},
"createdAt": "2026-05-26T16:00:00.000Z",
"updatedAt": "2026-05-26T16:00:00.000Z"
}
],
"pageInfo": {
"limit": 25,
"nextCursor": null,
"totalCount": 1
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "listWebhooks",
"x-mint": {
"metadata": {
"sidebarTitle": "List webhooks"
}
}
}
},
"/v0/webhooks/{id}": {
"get": {
"summary": "Get webhook",
"description": "Returns one webhook subscription for the current API principal. The signing secret is not returned after creation.",
"tags": [
"Webhooks"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Webhook subscription ID."
}
],
"responses": {
"200": {
"description": "Webhook subscription.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/WebhookSubscription"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"webhook": {
"summary": "Webhook subscription",
"value": {
"data": {
"id": "wh_123",
"principalId": "principal_123",
"url": "https://example.com/shodai/webhooks",
"status": "active",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
},
"createdAt": "2026-05-26T16:00:00.000Z",
"updatedAt": "2026-05-26T16:00:00.000Z"
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook subscription not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "getWebhook",
"x-mint": {
"metadata": {
"sidebarTitle": "Get webhook"
}
}
},
"patch": {
"summary": "Update webhook",
"description": "Updates a webhook URL, event types, filters, or status. The signing secret is not returned after creation.",
"tags": [
"Webhooks"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Webhook subscription ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookRequest"
},
"examples": {
"webhookUpdate": {
"summary": "Webhook subscription update",
"value": {
"status": "active",
"filters": {
"inputIds": [
"submitInitialPaymentProof"
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated webhook subscription.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/WebhookSubscription"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"webhook": {
"summary": "Updated webhook subscription",
"value": {
"data": {
"id": "wh_123",
"principalId": "principal_123",
"url": "https://example.com/shodai/webhooks",
"status": "active",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
},
"createdAt": "2026-05-26T16:00:00.000Z",
"updatedAt": "2026-05-26T16:00:00.000Z"
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"400": {
"description": "Invalid webhook update.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook subscription not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "updateWebhook",
"x-mint": {
"metadata": {
"sidebarTitle": "Update webhook"
}
}
},
"delete": {
"summary": "Disable webhook",
"description": "Disables a webhook subscription for the current API principal. The signing secret is not returned after creation.",
"tags": [
"Webhooks"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Webhook subscription ID."
}
],
"responses": {
"200": {
"description": "Disabled webhook subscription.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/WebhookSubscription"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook subscription not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "deleteWebhook",
"x-mint": {
"metadata": {
"sidebarTitle": "Disable webhook"
}
}
}
},
"/v0/webhooks/{id}/test": {
"post": {
"summary": "Send test webhook",
"description": "Sends a signed test payload to a webhook subscription. The signing secret is not returned after creation.",
"tags": [
"Webhooks"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Webhook subscription ID."
}
],
"responses": {
"201": {
"description": "Test delivery was queued and attempted.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/WebhookTestResponse"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"testDelivery": {
"summary": "Webhook test delivery result",
"value": {
"data": {
"ok": true,
"deliveryId": "whd_123",
"status": "succeeded",
"responseStatus": 204
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Webhook subscription not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "testWebhook",
"x-mint": {
"metadata": {
"sidebarTitle": "Test webhook"
}
}
}
},
"/v0/agreements": {
"get": {
"summary": "List agreements",
"description": "Lists agreement summaries visible to the current API key. Supports pagination, filtering, and sorting.",
"tags": [
"Agreement Records"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "state",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional current agreement state filter."
},
{
"name": "chainId",
"in": "query",
"required": false,
"schema": {
"type": "integer"
},
"description": "Optional deployed agreement chain filter. Use when the environment contains agreements across more than one supported chain."
},
{
"name": "createdAt[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt greater than this timestamp."
},
{
"name": "createdAt[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt greater than or equal to this timestamp."
},
{
"name": "createdAt[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt less than this timestamp."
},
{
"name": "createdAt[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt less than or equal to this timestamp."
},
{
"name": "updatedAt[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt greater than this timestamp."
},
{
"name": "updatedAt[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt greater than or equal to this timestamp."
},
{
"name": "updatedAt[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt less than this timestamp."
},
{
"name": "updatedAt[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt less than or equal to this timestamp."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"description": "Maximum number of records to return."
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Opaque cursor returned by a previous list response."
},
{
"name": "sort[createdAt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"description": "Sort by createdAt. Only one sort field may be supplied."
},
{
"name": "sort[updatedAt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"description": "Sort by updatedAt. Only one sort field may be supplied."
},
{
"name": "sort[displayName]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"description": "Sort by displayName. Only one sort field may be supplied."
}
],
"responses": {
"200": {
"description": "Paged agreement summaries visible to the current API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"pageInfo",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgreementSummary"
}
},
"pageInfo": {
"$ref": "#/components/schemas/PageInfo"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"agreements": {
"summary": "Agreement records visible to the API key",
"value": {
"data": [
{
"id": "agr_123",
"address": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"displayName": "Advisory Retainer",
"status": "Deployed",
"state": "AWAITING_PAYMENT",
"templateId": "did:template:service-retainer-v0-1",
"lastInputId": "submitInitialPaymentProof",
"lastInputAt": "2026-04-27T16:10:00.000Z",
"owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"createdAt": "2026-04-27T16:00:00.000Z",
"updatedAt": "2026-04-27T16:05:00.000Z"
}
],
"pageInfo": {
"limit": 25,
"nextCursor": null,
"totalCount": 1
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"400": {
"description": "Invalid list query.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "listAgreements",
"x-mint": {
"metadata": {
"sidebarTitle": "List agreements"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nUse `client.listAgreements(...)` when integrating with the TypeScript SDK."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "import { ApiClient } from '@shodai-network/agreements-api-client';\n\nconst client = new ApiClient({\n baseUrl: process.env.BASE_URL!,\n apiKey: process.env.API_KEY,\n});\n\nconst page = await client.listAgreements({\n chainId: 59141,\n state: 'AWAITING_PAYMENT',\n createdAt: { gte: '2026-05-01T00:00:00.000Z' },\n sort: { createdAt: 'desc' },\n limit: 25,\n});\nconsole.log(page.data, page.pageInfo.nextCursor);"
}
]
}
},
"/v0/agreements/validate": {
"post": {
"summary": "Preflight deployment request",
"description": "Checks whether authored agreement JSON plus target chain, deployment values, participant wallet mappings, and observer context are ready for deployment. This does not deploy the agreement.",
"tags": [
"Deployment"
],
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidateDirectAgreementRequest"
},
"examples": {
"deploymentPreflight": {
"summary": "Agreement plus deployment context",
"value": {
"agreement": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
},
"chainId": 59141,
"initValues": {
"retainerTitle": "Advisory Retainer"
},
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
]
}
}
}
}
}
},
"responses": {
"201": {
"description": "Deployment preflight summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/ValidateDirectAgreementResponse"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"ready": {
"summary": "Deployment preflight summary",
"value": {
"data": {
"templateId": "did:template:service-retainer-v0-1",
"participantVariableKeys": [
"serviceProviderRepresentative",
"clientRepresentative"
],
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
],
"variables": {
"serviceProviderRepresentative": "0x1111111111111111111111111111111111111111",
"clientRepresentative": "0x2222222222222222222222222222222222222222",
"retainerTitle": "Advisory Retainer"
},
"contributors": [
"0x1111111111111111111111111111111111111111",
"0x2222222222222222222222222222222222222222"
],
"warnings": []
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"400": {
"description": "Invalid deployment preflight payload.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "validateAgreementDeployment",
"x-mint": {
"metadata": {
"sidebarTitle": "Preflight deployment"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nThis endpoint validates the assembled deployment context before any EIP-712 permit is signed. The `testnet` API environment supports Linea Sepolia, Ethereum Sepolia, and Base Sepolia; the `production` API environment supports Linea Mainnet and Base Mainnet. Include the target `chainId` so preflight, signing, and deploy-with-permit requests all use the same supported chain. In SDK integrations, prefer `client.validateDeployment(...)` before `deployAgreementWithPermit(...)`. Generated API examples document request and response shape; complete deployable agreement JSON lives in /examples/simple and /examples/complex."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "const validation = await client.validateDeployment({\n agreement,\n chainId: 59141,\n initValues,\n participants,\n observers,\n});\n\nconsole.log(validation.variables);"
}
]
}
},
"/v0/agreements/validate-template": {
"post": {
"summary": "Validate agreement structure",
"description": "Checks only the authored agreement JSON and returns participant variable keys, input IDs, state IDs, and warnings. This does not validate deployment values, participant wallet addresses, signer, or permit data.",
"tags": [
"Authoring"
],
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"description": "Authored agreement JSON to validate before deployment preflight."
},
"examples": {
"agreement": {
"summary": "Authored agreement JSON",
"value": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Agreement structure validation summary.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/ValidateDirectAgreementTemplateResponse"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"validAgreement": {
"summary": "Structure validation result",
"value": {
"data": {
"templateId": "did:template:service-retainer-v0-1",
"participantVariableKeys": [
"serviceProviderRepresentative",
"clientRepresentative"
],
"inputIds": [
"submitInitialPaymentProof"
],
"stateIds": [
"AWAITING_PAYMENT",
"WORK_IN_PROGRESS"
],
"warnings": []
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"400": {
"description": "Invalid agreement JSON.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "validateAgreementTemplate",
"x-mint": {
"metadata": {
"sidebarTitle": "Validate agreement structure"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nThis endpoint checks authored agreement JSON only. It does not validate deployment values, participant wallet mappings, signer, or permit data. Generated API examples document request and response shape; complete deployable agreement JSON lives in /examples/simple and /examples/complex."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "const result = await client.validateTemplate(agreement);\n\nconsole.log(result.participantVariableKeys);\nconsole.log(result.inputIds);"
}
]
}
},
"/v0/agreements/deploy-with-permit": {
"post": {
"summary": "Deploy agreement",
"description": "Deploys authored agreement JSON using an EIP-712 permit. The API submits the on-chain transaction with the signed authorization and returns the deployed agreement record.",
"tags": [
"Deployment"
],
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectDeployAgreementWithPermitRequest"
},
"examples": {
"deployWithPermit": {
"summary": "Signed deployment request",
"value": {
"agreement": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
},
"displayName": "Advisory Retainer",
"chainId": 59141,
"initValues": {
"retainerTitle": "Advisory Retainer"
},
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
],
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"signer": "0x1111111111111111111111111111111111111111",
"deadline": 1776219513,
"signature": {
"v": 27,
"r": "0x1111111111111111111111111111111111111111111111111111111111111111",
"s": "0x2222222222222222222222222222222222222222222222222222222222222222"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Deployed agreement record.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/AgreementRecord"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"deployedAgreement": {
"summary": "Deployed agreement record",
"value": {
"data": {
"id": "agr_123",
"address": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"displayName": "Advisory Retainer",
"status": "Deployed",
"json": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
},
"state": "AWAITING_PAYMENT",
"variables": {
"serviceProviderRepresentative": "0x1111111111111111111111111111111111111111",
"clientRepresentative": "0x2222222222222222222222222222222222222222",
"retainerTitle": "Advisory Retainer"
},
"owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"contributors": [
"0x1111111111111111111111111111111111111111",
"0x2222222222222222222222222222222222222222"
],
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
],
"createdAt": "2026-04-27T16:00:00.000Z",
"updatedAt": "2026-04-27T16:05:00.000Z"
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"400": {
"description": "Invalid deployment request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "deployAgreementWithPermit",
"x-mint": {
"metadata": {
"sidebarTitle": "Deploy with permit"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nDeployment requires an API key plus a controlled wallet that can produce an EIP-712 signature. Use a `publicClient` connected to the selected `chainId`; the chain must be supported by the target API environment. The `testnet` API environment supports Linea Sepolia, Ethereum Sepolia, and Base Sepolia; the `production` API environment supports Linea Mainnet and Base Mainnet. In SDK integrations, use `deployAgreementWithPermit(...)` after reviewing deployment preflight output. Generated API examples document request and response shape; complete deployable agreement JSON lives in /examples/simple and /examples/complex."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "import { deployAgreementWithPermit } from '@shodai-network/agreements-api-client';\n\nconst chainId = 59141;\nconst validation = await client.validateDeployment({\n agreement,\n chainId,\n initValues,\n participants,\n observers,\n});\n\nconst deployed = await deployAgreementWithPermit({\n client,\n walletClient,\n publicClient,\n chainId,\n agreement,\n displayName: 'Advisory Retainer',\n initValues: validation.variables,\n participants,\n observers,\n});"
}
]
}
},
"/v0/agreements/documents/{documentId}": {
"get": {
"summary": "Get agreement document",
"description": "Returns the rendered prose document associated with an agreement documentId. Access requires the same authorization as reading the agreement record.",
"tags": [
"Agreement Documents"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "documentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Opaque hosted agreement document identifier."
}
],
"responses": {
"200": {
"description": "Rendered agreement prose document.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/AgreementDocumentResponse"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Not authorized to access this agreement document.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Agreement document not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/v0/agreements/{id}": {
"get": {
"summary": "Get agreement",
"description": "Returns a single agreement record, including agreement JSON and hosted record context.",
"tags": [
"Agreement Records"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Agreement ID or deployed agreement address."
}
],
"responses": {
"200": {
"description": "Agreement record.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/AgreementRecord"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"agreement": {
"summary": "Agreement record",
"value": {
"data": {
"id": "agr_123",
"address": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"displayName": "Advisory Retainer",
"status": "Deployed",
"json": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
},
"state": "AWAITING_PAYMENT",
"variables": {
"serviceProviderRepresentative": "0x1111111111111111111111111111111111111111",
"clientRepresentative": "0x2222222222222222222222222222222222222222",
"retainerTitle": "Advisory Retainer"
},
"owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"contributors": [
"0x1111111111111111111111111111111111111111",
"0x2222222222222222222222222222222222222222"
],
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
],
"createdAt": "2026-04-27T16:00:00.000Z",
"updatedAt": "2026-04-27T16:05:00.000Z"
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Agreement not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "getAgreement",
"x-mint": {
"metadata": {
"sidebarTitle": "Get agreement"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nUse `client.getAgreement(...)` to retrieve the hosted record and agreement JSON before operating on a deployed agreement."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "const agreement = await client.getAgreement('agr_123');"
}
]
}
},
"/v0/agreements/{id}/state": {
"get": {
"summary": "Get agreement state",
"description": "Returns the current state of an agreement. For deployed agreements, interpret the state against the authored agreement lifecycle.",
"tags": [
"Using Agreements"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Agreement ID or deployed agreement address."
}
],
"responses": {
"200": {
"description": "Agreement state payload.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/AgreementStateResponse"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"state": {
"summary": "Current agreement state",
"value": {
"data": {
"status": "Deployed",
"state": "AWAITING_PAYMENT"
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Agreement not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "getAgreementState",
"x-mint": {
"metadata": {
"sidebarTitle": "Get agreement state"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nUse the current state together with the authored agreement lifecycle before choosing an input to submit."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "const state = await client.getAgreementState('agr_123');"
}
]
}
},
"/v0/agreements/{id}/inputs": {
"get": {
"summary": "Get input history",
"description": "Returns recorded input submissions for the agreement. Use this to inspect what events have been submitted.",
"tags": [
"Using Agreements"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Agreement ID or deployed agreement address."
},
{
"name": "userId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional platform user ID filter."
},
{
"name": "inputId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Optional agreement input ID filter."
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"PENDING",
"MINED",
"FAILED"
]
},
"description": "Optional input submission status filter."
},
{
"name": "createdAt[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt greater than this timestamp."
},
{
"name": "createdAt[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt greater than or equal to this timestamp."
},
{
"name": "createdAt[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt less than this timestamp."
},
{
"name": "createdAt[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with createdAt less than or equal to this timestamp."
},
{
"name": "updatedAt[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt greater than this timestamp."
},
{
"name": "updatedAt[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt greater than or equal to this timestamp."
},
{
"name": "updatedAt[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt less than this timestamp."
},
{
"name": "updatedAt[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Include records with updatedAt less than or equal to this timestamp."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
},
"description": "Maximum number of records to return."
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Opaque cursor returned by a previous list response."
},
{
"name": "sort[createdAt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"description": "Sort by createdAt. Only one sort field may be supplied."
},
{
"name": "sort[updatedAt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"description": "Sort by updatedAt. Only one sort field may be supplied."
}
],
"responses": {
"200": {
"description": "Paged cached input records.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"pageInfo",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgreementInputRecord"
}
},
"pageInfo": {
"$ref": "#/components/schemas/PageInfo"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"inputHistory": {
"summary": "Submitted agreement inputs",
"value": {
"data": [
{
"agreementId": "agr_123",
"agreementAddress": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"inputId": "submitInitialPaymentProof",
"txHash": "0x4444444444444444444444444444444444444444444444444444444444444444",
"payload": "0x...",
"values": {
"paymentReference": "wire-2026-04-27-001"
},
"status": "MINED",
"createdAt": "2026-04-27T16:10:00.000Z",
"updatedAt": "2026-04-27T16:11:00.000Z"
}
],
"pageInfo": {
"limit": 25,
"nextCursor": null,
"totalCount": 1
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Agreement not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "listAgreementInputs",
"x-mint": {
"metadata": {
"sidebarTitle": "Get input history"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nUse `client.listAgreementInputs(...)` to inspect submitted events before deciding the next lifecycle action."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "const page = await client.listAgreementInputs('agr_123', { limit: 25 });\nconsole.log(page.data, page.pageInfo.nextCursor);"
}
]
}
},
"/v0/agreements/{id}/input": {
"post": {
"summary": "Submit input with permit",
"description": "Submits a signed input to a deployed agreement. The input ID and values must match an input defined by the agreement JSON, and the signer must be allowed by that input.",
"tags": [
"Using Agreements"
],
"security": [
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Agreement ID or deployed agreement address."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProcessInputRequest"
},
"examples": {
"signedInput": {
"summary": "Signed agreement input",
"value": {
"inputId": "submitInitialPaymentProof",
"values": {
"paymentReference": "wire-2026-04-27-001"
},
"signer": "0x2222222222222222222222222222222222222222",
"deadline": 1776219513,
"signature": {
"v": 27,
"r": "0x1111111111111111111111111111111111111111111111111111111111111111",
"s": "0x2222222222222222222222222222222222222222222222222222222222222222"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created input record.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"$ref": "#/components/schemas/AgreementInputRecord"
},
"meta": {
"$ref": "#/components/schemas/ResponseMeta"
}
}
},
"examples": {
"createdInput": {
"summary": "Created input record",
"value": {
"data": {
"agreementId": "agr_123",
"agreementAddress": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"inputId": "submitInitialPaymentProof",
"txHash": "0x4444444444444444444444444444444444444444444444444444444444444444",
"payload": "0x...",
"values": {
"paymentReference": "wire-2026-04-27-001"
},
"status": "MINED",
"createdAt": "2026-04-27T16:10:00.000Z",
"updatedAt": "2026-04-27T16:11:00.000Z"
},
"meta": {
"apiVersion": "v0",
"requestId": "req_123"
}
}
}
}
}
}
},
"400": {
"description": "Invalid signed input payload.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The API key is not allowed to access this resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Agreement not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"operationId": "submitAgreementInputWithPermit",
"x-mint": {
"metadata": {
"sidebarTitle": "Submit input with permit"
},
"content": "\nFor the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).\n\n\nInput submission requires a wallet that can sign for an account allowed by the authored input `issuer`. Use the deployed agreement record's `chainId` and contract address when creating the EIP-712 signature. In SDK integrations, use `submitAgreementInputWithPermit(...)` to sign and submit in one flow. Generated API examples document request and response shape; choose input IDs and values from the deployed agreement JSON."
},
"x-codeSamples": [
{
"lang": "typescript",
"label": "SDK",
"source": "import { submitAgreementInputWithPermit } from '@shodai-network/agreements-api-client';\n\nconst input = await submitAgreementInputWithPermit({\n client,\n agreementId: 'agr_123',\n walletClient,\n publicClient,\n chainId: agreementRecord.chainId,\n agreementContractAddress: '0x3333333333333333333333333333333333333333',\n agreement,\n inputId: 'submitInitialPaymentProof',\n values: { paymentReference: 'wire-2026-04-27-001' },\n});"
}
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Canonical API-key credential. Send X-API-Key: cns_pk_..., or Authorization: Bearer cns_pk_... only as an API-key compatibility alias. OAuth and JWT bearer tokens are not supported.",
"x-default": "YOUR_API_KEY"
}
},
"schemas": {
"HealthResponse": {
"type": "object",
"required": [
"status",
"service",
"timestamp"
],
"properties": {
"status": {
"type": "string",
"example": "ok"
},
"service": {
"type": "string",
"example": "external-api"
},
"timestamp": {
"type": "string",
"format": "date-time"
}
}
},
"ResponseMeta": {
"type": "object",
"required": [
"apiVersion",
"requestId"
],
"properties": {
"apiVersion": {
"type": "string",
"example": "v0"
},
"requestId": {
"type": "string",
"description": "Correlation ID for support and debugging."
}
}
},
"PageInfo": {
"type": "object",
"required": [
"limit",
"nextCursor"
],
"properties": {
"limit": {
"type": "integer",
"example": 25
},
"nextCursor": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"totalCount": {
"type": "integer",
"description": "Total number of matching records when available."
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"requestId"
],
"properties": {
"code": {
"type": "string",
"example": "unauthorized",
"description": "Stable machine-readable error code."
},
"message": {
"type": "string",
"example": "Missing API key",
"description": "Safe human-readable error summary."
},
"details": {
"description": "Optional field errors or upstream-safe context."
},
"requestId": {
"type": "string",
"description": "Correlation ID for support and debugging."
}
}
}
}
},
"AgreementSummary": {
"type": "object",
"required": [
"id",
"chainId",
"displayName",
"status",
"createdAt",
"updatedAt"
],
"description": "Compact agreement record returned by list endpoints. Read a single agreement to retrieve full agreement JSON, participants, observers, and on-chain detail.",
"properties": {
"id": {
"type": "string",
"description": "Agreement record ID."
},
"address": {
"type": "string",
"description": "Deployed agreement address, when deployed."
},
"chainId": {
"type": "integer",
"description": "Chain ID for the deployed agreement."
},
"status": {
"type": "string",
"enum": [
"Draft",
"Deployed"
],
"description": "Agreement record status."
},
"state": {
"type": "string",
"description": "Cached agreement state, when available."
},
"templateId": {
"type": "string",
"description": "Agreement metadata templateId or id value, when present."
},
"lastInputId": {
"type": "string",
"description": "Most recent submitted input ID, when available."
},
"lastInputAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent submitted input, when available."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Record update timestamp."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Record creation timestamp."
},
"displayName": {
"type": "string",
"description": "Human-readable record label."
},
"owner": {
"type": "string",
"description": "Wallet address associated with hosted record ownership."
},
"documentId": {
"type": "string",
"description": "Opaque hosted agreement document identifier used by /agreements/documents/{documentId}."
},
"docUri": {
"type": "string",
"description": "Optional document URI associated with the deployed agreement, typically /agreements/documents/{documentId}."
}
},
"example": {
"id": "agr_123",
"address": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"displayName": "Advisory Retainer",
"status": "Deployed",
"state": "AWAITING_PAYMENT",
"templateId": "did:template:service-retainer-v0-1",
"lastInputId": "submitInitialPaymentProof",
"lastInputAt": "2026-04-27T16:10:00.000Z",
"owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"createdAt": "2026-04-27T16:00:00.000Z",
"updatedAt": "2026-04-27T16:05:00.000Z"
}
},
"AgreementRecord": {
"type": "object",
"required": [
"id",
"chainId",
"displayName",
"status",
"json",
"createdAt",
"updatedAt"
],
"description": "Hosted record for an authored or deployed agreement. Use the state and input-history routes when you need current execution state or submitted input history.",
"properties": {
"id": {
"type": "string",
"description": "Agreement record ID."
},
"address": {
"type": "string",
"description": "Deployed agreement address, when deployed."
},
"chainId": {
"type": "integer",
"description": "Chain ID for the deployed agreement."
},
"status": {
"type": "string",
"enum": [
"Draft",
"Deployed"
],
"description": "Agreement record status."
},
"lastInputId": {
"type": "string",
"description": "Most recent submitted input ID, when available."
},
"lastInputAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent submitted input, when available."
},
"json": {
"type": "object",
"additionalProperties": true,
"description": "Authored agreement JSON."
},
"state": {
"type": "string",
"description": "Cached agreement state, when available."
},
"variables": {
"type": "object",
"additionalProperties": true,
"description": "Current stored agreement values."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Record update timestamp."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Record creation timestamp."
},
"displayName": {
"type": "string",
"description": "Human-readable record label."
},
"owner": {
"type": "string",
"description": "Wallet address associated with hosted record ownership."
},
"documentId": {
"type": "string",
"description": "Opaque hosted agreement document identifier used by /agreements/documents/{documentId}."
},
"docUri": {
"type": "string",
"description": "Optional document URI associated with the deployed agreement, typically /agreements/documents/{documentId}."
},
"contributors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Wallet addresses associated with agreement activity."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParticipantRecord"
},
"description": "Participants associated with agreement participant variables."
},
"observers": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "Observer email addresses associated with the agreement record."
},
"onChain": {
"type": "object",
"additionalProperties": true,
"description": "On-chain agreement data when available."
}
},
"example": {
"id": "agr_123",
"address": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"displayName": "Advisory Retainer",
"status": "Deployed",
"json": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
},
"state": "AWAITING_PAYMENT",
"variables": {
"serviceProviderRepresentative": "0x1111111111111111111111111111111111111111",
"clientRepresentative": "0x2222222222222222222222222222222222222222",
"retainerTitle": "Advisory Retainer"
},
"owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"contributors": [
"0x1111111111111111111111111111111111111111",
"0x2222222222222222222222222222222222222222"
],
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
],
"createdAt": "2026-04-27T16:00:00.000Z",
"updatedAt": "2026-04-27T16:05:00.000Z"
}
},
"AgreementDocumentResponse": {
"type": "object",
"required": [
"documentId",
"agreementId",
"chainId",
"displayName",
"contentType",
"content"
],
"description": "Authenticated resolver response for hosted agreement prose associated with an on-chain docUri.",
"properties": {
"documentId": {
"type": "string",
"description": "Opaque hosted agreement document identifier."
},
"docUri": {
"type": "string",
"description": "Hosted document URI recorded with the agreement."
},
"agreementId": {
"type": "string",
"description": "Hosted agreement record ID."
},
"agreementAddress": {
"type": "string",
"description": "Deployed agreement address, when deployed."
},
"chainId": {
"type": "integer",
"description": "Agreement chain ID."
},
"displayName": {
"type": "string",
"description": "Human-readable agreement label."
},
"contentType": {
"type": "string",
"description": "MIME type for the rendered prose content."
},
"content": {
"type": "string",
"description": "Rendered agreement prose with stored variable values applied."
},
"docHash": {
"type": "string",
"description": "On-chain document hash, when available."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Agreement record update timestamp."
}
},
"example": {
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"agreementId": "agr_123",
"agreementAddress": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"displayName": "Advisory Retainer",
"contentType": "text/markdown",
"content": "# Advisory Retainer\n\nService agreement between provider and client.",
"docHash": "0x325698d320b8d4e884a856480df1d934877cb71cd39f08bd3c5a268bd21d82db",
"updatedAt": "2026-04-27T16:05:00.000Z"
}
},
"ValidateDirectAgreementRequest": {
"type": "object",
"required": [
"agreement",
"chainId"
],
"description": "Deployment preflight request for authored agreement JSON and its deployment context.",
"properties": {
"agreement": {
"type": "object",
"additionalProperties": true,
"description": "Authored agreement JSON to preflight before deployment."
},
"chainId": {
"type": "integer",
"description": "Supported agreement deployment chain ID to preflight. Use the same value when signing and submitting the deploy-with-permit request."
},
"initValues": {
"type": "object",
"additionalProperties": true,
"description": "Deployment values for variables required when the agreement is created."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DirectParticipantRecord"
},
"description": "Participant wallet mappings for participant address variables."
},
"observers": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "Optional observer email addresses to associate with the agreement record."
}
},
"example": {
"agreement": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
},
"chainId": 59141,
"initValues": {
"retainerTitle": "Advisory Retainer"
},
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
]
}
},
"ValidateDirectAgreementResponse": {
"type": "object",
"required": [
"templateId",
"participantVariableKeys",
"participants",
"observers",
"variables",
"contributors",
"warnings"
],
"properties": {
"templateId": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Agreement metadata templateId or id value, when present."
},
"participantVariableKeys": {
"type": "array",
"items": {
"type": "string"
},
"description": "Participant address variable keys found in the agreement JSON."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DirectParticipantRecord"
},
"description": "Normalized participant wallet mappings."
},
"observers": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "Normalized observer email addresses."
},
"variables": {
"type": "object",
"additionalProperties": true,
"description": "Deployment values after participant wallet mappings are applied."
},
"contributors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Wallet addresses that may contribute to agreement visibility or activity."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warnings to review before deployment."
}
},
"example": {
"templateId": "did:template:service-retainer-v0-1",
"participantVariableKeys": [
"serviceProviderRepresentative",
"clientRepresentative"
],
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
],
"variables": {
"serviceProviderRepresentative": "0x1111111111111111111111111111111111111111",
"clientRepresentative": "0x2222222222222222222222222222222222222222",
"retainerTitle": "Advisory Retainer"
},
"contributors": [
"0x1111111111111111111111111111111111111111",
"0x2222222222222222222222222222222222222222"
],
"warnings": []
}
},
"ValidateDirectAgreementTemplateResponse": {
"type": "object",
"required": [
"templateId",
"participantVariableKeys",
"inputIds",
"stateIds",
"warnings"
],
"properties": {
"templateId": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Agreement metadata templateId or id value, when present."
},
"participantVariableKeys": {
"type": "array",
"items": {
"type": "string"
},
"description": "Participant address variable keys found in the agreement JSON."
},
"inputIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Input IDs defined in the agreement JSON."
},
"stateIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "State IDs defined in the agreement JSON."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warnings to review before preparing deployment."
}
},
"example": {
"templateId": "did:template:service-retainer-v0-1",
"participantVariableKeys": [
"serviceProviderRepresentative",
"clientRepresentative"
],
"inputIds": [
"submitInitialPaymentProof"
],
"stateIds": [
"AWAITING_PAYMENT",
"WORK_IN_PROGRESS"
],
"warnings": []
}
},
"PermitSignature": {
"type": "object",
"required": [
"v",
"r",
"s"
],
"description": "EIP-712 signature parts.",
"properties": {
"v": {
"type": "integer",
"description": "Recovery identifier."
},
"r": {
"type": "string",
"description": "Signature r value."
},
"s": {
"type": "string",
"description": "Signature s value."
}
},
"example": {
"v": 27,
"r": "0x1111111111111111111111111111111111111111111111111111111111111111",
"s": "0x2222222222222222222222222222222222222222222222222222222222222222"
}
},
"DirectDeployAgreementWithPermitRequest": {
"type": "object",
"required": [
"agreement",
"displayName",
"chainId",
"signer",
"deadline",
"signature"
],
"description": "Deploys authored agreement JSON with deployment values, participant mappings, and an EIP-712 permit.",
"properties": {
"agreement": {
"type": "object",
"additionalProperties": true,
"description": "Authored agreement JSON to deploy."
},
"displayName": {
"type": "string",
"description": "Human-readable label for the agreement record."
},
"docUri": {
"type": "string",
"description": "Optional document URI to associate with the deployed agreement. SDK helpers default this to /agreements/documents/{documentId}."
},
"documentId": {
"type": "string",
"description": "Opaque hosted document identifier associated with docUri. SDK helpers generate this when docUri is omitted."
},
"initValues": {
"type": "object",
"additionalProperties": true,
"description": "Deployment values for variables required when the agreement is created."
},
"participants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DirectParticipantRecord"
},
"description": "Participant wallet mappings for participant address variables."
},
"observers": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "Optional observer email addresses to associate with the agreement record."
},
"notificationTemplate": {
"allOf": [
{
"$ref": "#/components/schemas/NotificationTemplate"
}
],
"description": "Optional agreement-scoped notification template. Rules with channel external_webhook emit agreement.notification.triggered webhooks instead of emails."
},
"chainId": {
"type": "integer",
"description": "Supported agreement deployment chain ID. Must match the chain used for deployment preflight, permit signing, and transaction submission."
},
"signer": {
"type": "string",
"description": "Wallet address that signed the EIP-712 deployment permit."
},
"deadline": {
"type": "integer",
"description": "Unix timestamp in seconds when the deployment permit expires."
},
"signature": {
"$ref": "#/components/schemas/PermitSignature"
}
},
"example": {
"agreement": {
"metadata": {
"templateId": "did:template:service-retainer-v0-1",
"name": "Service Retainer"
},
"variables": {
"serviceProviderRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"clientRepresentative": {
"type": "address",
"subtype": "participant",
"validation": {
"required": true
}
},
"retainerTitle": {
"type": "string",
"validation": {
"required": true
}
}
},
"content": {
"type": "md",
"data": "# ${variables.retainerTitle}\n\nService agreement between provider and client."
},
"execution": {
"initialize": {
"initialState": "AWAITING_PAYMENT",
"data": {}
},
"states": {
"AWAITING_PAYMENT": {
"description": "Waiting for initial payment proof."
},
"WORK_IN_PROGRESS": {
"description": "Provider is performing the service."
}
},
"inputs": {
"submitInitialPaymentProof": {
"issuer": {
"type": "participant",
"variable": "clientRepresentative"
},
"schema": {
"paymentReference": {
"type": "string",
"validation": {
"required": true
}
}
}
}
},
"transitions": [
{
"from": "AWAITING_PAYMENT",
"to": "WORK_IN_PROGRESS",
"conditions": [
{
"input": "submitInitialPaymentProof"
}
]
}
]
}
},
"displayName": "Advisory Retainer",
"chainId": 59141,
"initValues": {
"retainerTitle": "Advisory Retainer"
},
"participants": [
{
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "clientRepresentative",
"walletAddress": "0x2222222222222222222222222222222222222222",
"email": "client@example.com"
}
],
"observers": [
"legal@example.com"
],
"documentId": "7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"docUri": "https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d",
"signer": "0x1111111111111111111111111111111111111111",
"deadline": 1776219513,
"signature": {
"v": 27,
"r": "0x1111111111111111111111111111111111111111111111111111111111111111",
"s": "0x2222222222222222222222222222222222222222222222222222222222222222"
}
}
},
"NotificationTemplate": {
"type": "object",
"required": [
"rules"
],
"properties": {
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Template metadata. Scope, principal, agreement, and final id are assigned by the API for deploy-time templates."
},
"rules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NotificationRule"
}
}
}
},
"NotificationRule": {
"type": "object",
"required": [
"id",
"name",
"trigger",
"recipients",
"notification"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"trigger": {
"type": "object",
"additionalProperties": true,
"description": "Notification trigger. Supports onTransition and temporal trigger shapes."
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Recipient references such as participant variable keys, @observers, or *."
},
"notification": {
"type": "object",
"required": [
"subject",
"body"
],
"properties": {
"channel": {
"type": "string",
"enum": [
"email",
"external_webhook"
],
"description": "Use external_webhook for partner webhook delivery. Defaults to email for catalog templates."
},
"subject": {
"type": "string"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"ctaLabel": {
"type": "string"
}
}
},
"constraints": {
"type": "object",
"additionalProperties": true
}
}
},
"DirectParticipantRecord": {
"type": "object",
"required": [
"variableKey",
"walletAddress"
],
"properties": {
"variableKey": {
"type": "string",
"description": "Participant address variable key in the agreement JSON."
},
"walletAddress": {
"type": "string",
"description": "Wallet address for this participant. Required for direct API deployment."
},
"email": {
"type": "string",
"format": "email",
"description": "Optional participant email context."
},
"firstName": {
"type": "string",
"description": "Optional participant first name."
},
"lastName": {
"type": "string",
"description": "Optional participant last name."
},
"walletBinding": {
"type": "string",
"enum": [
"verified_via_auth",
"verified_via_siwe",
"partner_asserted"
],
"description": "Wallet provenance recorded by the API."
}
},
"description": "Participant mapping for direct API validation and deployment requests.",
"example": {
"variableKey": "serviceProviderRepresentative",
"walletAddress": "0x1111111111111111111111111111111111111111"
}
},
"ParticipantRecord": {
"type": "object",
"required": [
"variableKey"
],
"properties": {
"variableKey": {
"type": "string",
"description": "Participant address variable key in the agreement JSON."
},
"email": {
"type": "string",
"format": "email",
"description": "Participant email context."
},
"firstName": {
"type": "string",
"description": "Participant first name, when available."
},
"lastName": {
"type": "string",
"description": "Participant last name, when available."
},
"walletAddress": {
"type": "string",
"description": "Participant wallet address, when available."
},
"walletBinding": {
"type": "string",
"enum": [
"verified_via_auth",
"verified_via_siwe",
"partner_asserted"
],
"description": "Wallet provenance recorded by the API."
}
},
"example": {
"variableKey": "clientRepresentative",
"email": "client@example.com",
"walletAddress": "0x2222222222222222222222222222222222222222",
"walletBinding": "partner_asserted"
}
},
"AgreementStateResponse": {
"type": "object",
"required": [
"status",
"state"
],
"properties": {
"status": {
"type": "string",
"enum": [
"Draft",
"Deployed"
],
"description": "Agreement record status."
},
"state": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Current agreement state, or null when no state is available."
}
},
"description": "Current agreement status and state.",
"example": {
"status": "Deployed",
"state": "AWAITING_PAYMENT"
}
},
"AgreementInputRecord": {
"type": "object",
"required": [
"agreementId",
"agreementAddress",
"chainId",
"inputId",
"txHash",
"payload",
"values",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"agreementId": {
"type": "string",
"description": "Hosted agreement record ID associated with this input."
},
"agreementAddress": {
"type": "string",
"description": "Deployed agreement address associated with this input."
},
"chainId": {
"type": "integer",
"description": "Chain ID for the deployed agreement."
},
"inputId": {
"type": "string",
"description": "Input ID submitted to the agreement."
},
"userId": {
"type": "string",
"description": "Platform user ID associated with the submission, when available."
},
"blockNumber": {
"type": "integer",
"description": "Block number for the mined input transaction, when available."
},
"payload": {
"type": "string",
"description": "Encoded input payload retained by the API."
},
"values": {
"type": "object",
"additionalProperties": true,
"description": "Business values submitted with the input."
},
"txHash": {
"type": "string",
"description": "Transaction hash for the input submission."
},
"error": {
"type": "string",
"description": "Error message when the input submission failed."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Input record creation timestamp."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Input record update timestamp."
},
"status": {
"type": "string",
"enum": [
"PENDING",
"MINED",
"FAILED"
],
"description": "Input submission status."
}
},
"example": {
"agreementId": "agr_123",
"agreementAddress": "0x3333333333333333333333333333333333333333",
"chainId": 59141,
"inputId": "submitInitialPaymentProof",
"txHash": "0x4444444444444444444444444444444444444444444444444444444444444444",
"payload": "0x...",
"values": {
"paymentReference": "wire-2026-04-27-001"
},
"status": "MINED",
"createdAt": "2026-04-27T16:10:00.000Z",
"updatedAt": "2026-04-27T16:11:00.000Z"
}
},
"WebhookFilters": {
"type": "object",
"properties": {
"agreementIds": {
"type": "array",
"items": {
"type": "string"
}
},
"templateIds": {
"type": "array",
"items": {
"type": "string"
}
},
"inputIds": {
"type": "array",
"items": {
"type": "string"
}
},
"fromStates": {
"type": "array",
"items": {
"type": "string"
}
},
"toStates": {
"type": "array",
"items": {
"type": "string"
}
},
"ruleIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Optional filters applied before delivery. agreementIds and templateIds apply to both agreement.transitioned and agreement.notification.triggered. inputIds, fromStates, and toStates apply to agreement.transitioned and to notification events with transition data. ruleIds apply to agreement.notification.triggered events."
},
"WebhookSubscription": {
"type": "object",
"required": [
"id",
"principalId",
"url",
"status",
"eventTypes",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Webhook subscription ID."
},
"principalId": {
"type": "string",
"description": "External API principal that owns this webhook."
},
"createdByApiKeyId": {
"type": "string",
"description": "API key that created the webhook, for audit only."
},
"url": {
"type": "string",
"format": "uri",
"description": "HTTPS endpoint that receives signed webhook POSTs."
},
"status": {
"type": "string",
"enum": [
"active",
"disabled"
],
"description": "Webhook subscription status."
},
"eventTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"agreement.transitioned",
"agreement.notification.triggered"
]
},
"description": "Subscribable event types this webhook can receive."
},
"filters": {
"$ref": "#/components/schemas/WebhookFilters"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Webhook creation timestamp."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Webhook update timestamp."
}
},
"example": {
"id": "wh_123",
"principalId": "principal_123",
"url": "https://example.com/shodai/webhooks",
"status": "active",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
},
"createdAt": "2026-05-26T16:00:00.000Z",
"updatedAt": "2026-05-26T16:00:00.000Z"
}
},
"CreateWebhookRequest": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "HTTPS endpoint that receives signed webhook POSTs."
},
"eventTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"agreement.transitioned",
"agreement.notification.triggered"
]
},
"description": "Subscribable event types. On create, omitted, null, or empty eventTypes defaults to agreement.transitioned."
},
"filters": {
"$ref": "#/components/schemas/WebhookFilters"
}
},
"example": {
"url": "https://example.com/shodai/webhooks",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
}
}
},
"CreateWebhookResponse": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookSubscription"
},
{
"type": "object",
"required": [
"secret"
],
"properties": {
"secret": {
"type": "string",
"description": "Webhook signing secret. Store it immediately; it is returned only on creation."
}
}
}
],
"example": {
"id": "wh_123",
"principalId": "principal_123",
"url": "https://example.com/shodai/webhooks",
"status": "active",
"eventTypes": [
"agreement.transitioned",
"agreement.notification.triggered"
],
"filters": {
"templateIds": [
"did:template:service-retainer-v0-1"
],
"ruleIds": [
"deployment-follow-up"
]
},
"createdAt": "2026-05-26T16:00:00.000Z",
"updatedAt": "2026-05-26T16:00:00.000Z",
"secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
},
"UpdateWebhookRequest": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Replacement HTTPS endpoint URL."
},
"status": {
"type": "string",
"enum": [
"active",
"disabled"
],
"description": "Enable or disable delivery."
},
"eventTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"agreement.transitioned",
"agreement.notification.triggered"
]
},
"description": "Replacement subscribable event types. On update, omitted eventTypes leaves the current value unchanged; null or an empty array resets to agreement.transitioned."
},
"filters": {
"$ref": "#/components/schemas/WebhookFilters"
}
},
"example": {
"status": "active",
"filters": {
"inputIds": [
"submitInitialPaymentProof"
]
}
}
},
"WebhookTestResponse": {
"type": "object",
"required": [
"ok",
"deliveryId",
"status"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True only when the immediate test delivery attempt succeeded."
},
"deliveryId": {
"type": "string",
"description": "Delivery record ID for the test send."
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed",
"retry_pending"
],
"description": "Recorded status after the immediate test delivery attempt."
},
"responseStatus": {
"type": "number",
"description": "HTTP status returned by the webhook receiver when available."
},
"error": {
"type": "string",
"description": "Failure reason recorded for failed or retry-pending test deliveries."
}
},
"example": {
"ok": true,
"deliveryId": "whd_123",
"status": "succeeded",
"responseStatus": 204
}
},
"ProcessInputRequest": {
"type": "object",
"required": [
"inputId",
"values",
"signer",
"deadline",
"signature"
],
"description": "Signed input submission for a deployed agreement.",
"properties": {
"inputId": {
"type": "string",
"description": "Input ID defined in the agreement JSON."
},
"values": {
"type": "object",
"additionalProperties": true,
"description": "Business values submitted for this input."
},
"signer": {
"type": "string",
"description": "Wallet address that signed the EIP-712 input permit."
},
"deadline": {
"type": "integer",
"description": "Unix timestamp in seconds when the input permit expires."
},
"signature": {
"$ref": "#/components/schemas/PermitSignature"
}
},
"example": {
"inputId": "submitInitialPaymentProof",
"values": {
"paymentReference": "wire-2026-04-27-001"
},
"signer": "0x2222222222222222222222222222222222222222",
"deadline": 1776219513,
"signature": {
"v": 27,
"r": "0x1111111111111111111111111111111111111111111111111111111111111111",
"s": "0x2222222222222222222222222222222222222222222222222222222222222222"
}
}
}
}
}
}