Skip to main content
GET
/
v0
/
agreements
/
{id}
cURL
curl --request GET \
  --url https://test-api.shodai.network/v0/agreements/{id} \
  --header 'X-API-Key: <api-key>'
{
  "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"
  }
}
Use client.getAgreement(...) to retrieve the hosted record and agreement JSON before operating on a deployed agreement.

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.

Path Parameters

id
string
required

Agreement ID or deployed agreement address.

Response

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