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",
  "signer": "0x1111111111111111111111111111111111111111",
  "deadline": 1776219513,
  "signature": {
    "v": 27,
    "r": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "s": "0x2222222222222222222222222222222222222222222222222222222222222222"
  }
}
'
{
  "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",
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.shodai.network/llms.txt

Use this file to discover all available pages before exploring further.

Deployment requires an API key plus a controlled wallet that can produce an EIP-712 signature. 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

API key. Send this value in the X-API-Key request header.

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.

​
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.

​
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.

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.

​
id
string
required

Agreement record ID.

​
chainId
integer
required

Chain ID for the deployed agreement.

​
status
enum<string>
required

Agreement record status.

Available options:
Draft,
Deployed
​
json
object
required

Authored agreement JSON.

​
updatedAt
string<date-time>
required

Record update timestamp.

​
createdAt
string<date-time>
required

Record creation timestamp.

​
displayName
string
required

Human-readable record label.

​
address
string

Deployed agreement address, when deployed.

​
lastInputId
string

Most recent submitted input ID, when available.

​
lastInputAt
string<date-time>

Time of the most recent submitted input, when available.

​
state
string

Cached agreement state, when available.

​
variables
object

Current stored agreement values.

​
owner
string

Wallet address associated with hosted record ownership.

​
docUri
string

Optional document URI associated with the deployed agreement.

​
contributors
string[]

Wallet addresses associated with agreement activity.

​
participants
object[]

Participants associated with agreement participant variables.

​
observers
string<email>[]

Observer email addresses associated with the agreement record.

​
onChain
object

On-chain agreement data when available.