Skip to main content
POST
/
v0
/
agreements
/
deploy-with-permit
cURL
curl --request POST \
  --url https://test-api.shodai.network/v0/agreements/deploy-with-permit \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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,
  "signer": "0x1111111111111111111111111111111111111111",
  "deadline": 1776219513,
  "signature": {
    "v": 27,
    "r": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "s": "0x2222222222222222222222222222222222222222222222222222222222222222"
  }
}
'
{
  "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"
  }
}
Deployment 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.

Authorizations

​
X-API-Key
string
header
default:YOUR_API_KEY
required

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.

Body

application/json

Deploys authored agreement JSON with deployment values, participant mappings, and an EIP-712 permit.

​
agreement
object
required

Authored agreement JSON to deploy.

​
displayName
string
required

Human-readable label for the agreement record.

​
chainId
integer
required

Supported agreement deployment chain ID. Must match the chain used for deployment preflight, permit signing, and transaction submission.

​
signer
string
required

Wallet address that signed the EIP-712 deployment permit.

​
deadline
integer
required

Unix timestamp in seconds when the deployment permit expires.

​
signature
object
required

EIP-712 signature parts.

Example:
{
  "v": 27,
  "r": "0x1111111111111111111111111111111111111111111111111111111111111111",
  "s": "0x2222222222222222222222222222222222222222222222222222222222222222"
}
​
docUri
string

Optional document URI to associate with the deployed agreement. SDK helpers default this to /agreements/documents/{documentId}.

​
documentId
string

Opaque hosted document identifier associated with docUri. SDK helpers generate this when docUri is omitted.

​
initValues
object

Deployment values for variables required when the agreement is created.

​
participants
object[]

Participant wallet mappings for participant address variables.

​
observers
string<email>[]

Optional observer email addresses to associate with the agreement record.

Response

Deployed agreement record.

​
data
object
required

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.

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"
}
​
meta
object
required