Deployment

Deploy agreement

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.

post/v0/agreements/deploy-with-permit

Request

Base URL: https://test-api.shodai.network
URL: https://test-api.shodai.network/v0/agreements/deploy-with-permit
Auth: one of:
- API key in header X-API-Key
- HTTP bearer

Request body

agreementobject required

Authored agreement JSON to deploy.

displayNamestring required

Human-readable label for the agreement record.

docUristring

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

documentIdstring

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

initValuesobject

Deployment values for variables required when the agreement is created.

observersstring[]

Optional observer email addresses to associate with the agreement record.

chainIdinteger required

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

signerstring required

Wallet address that signed the EIP-712 deployment permit.

deadlineinteger required

Unix timestamp in seconds when the deployment permit expires.

Example request

{
  "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"
  }
}

Response

Deployed agreement record.

Example response

{
  "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"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.