---
title: "Deploy agreement"
method: POST
path: "/v0/agreements/deploy-with-permit"
tags: ["Deployment"]
---

# Deploy agreement

`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

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.

## Request body

- DirectDeployAgreementWithPermitRequest: 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.
  - `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` DirectParticipantRecord[]: Participant wallet mappings for participant address variables.
    - `variableKey` string, required: Participant address variable key in the agreement JSON.
    - `walletAddress` string, required: Wallet address for this participant. Required for direct API deployment.
    - `email` string, email: Optional participant email context.
    - `firstName` string: Optional participant first name.
    - `lastName` string: Optional participant last name.
    - `walletBinding` 'verified_via_auth' | 'verified_via_siwe' | 'partner_asserted': Wallet provenance recorded by the API.
  - `observers` string[]: Optional observer email addresses to associate with the agreement record.
  - `notificationTemplate` NotificationTemplate
    - `metadata` object: Template metadata. Scope, account, agreement, and final id are assigned by the API for deploy-time templates.
    - `rules` NotificationRule[], required
      - `id` string, required
      - `name` string, required
      - `description` string
      - `enabled` boolean
      - `trigger` object, required: Notification trigger. Supports onTransition and temporal trigger shapes.
      - `recipients` string[], required: Recipient references such as participant variable keys, @observers, or *.
      - `notification` object, required
        - `channel` 'email' | 'external_webhook': Use external_webhook for partner webhook delivery. Defaults to email for catalog templates.
        - `subject` string, required
        - `title` string
        - `body` string, required
        - `ctaLabel` string
      - `constraints` object
  - `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` PermitSignature, required: EIP-712 signature parts.
    - `v` integer, required: Recovery identifier.
    - `r` string, required: Signature r value.
    - `s` string, required: Signature s value.

## Response `201`

Deployed agreement record.

- object
  - `data` AgreementRecord, 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.
    - `id` string, required: Agreement record ID.
    - `operationId` string: Stable durable permit-operation identity, when API initiated.
    - `operationLifecycle` 'intent_recorded' | 'transaction_ready' | 'confirmed' | 'completed' | 'failed': Durable permit-operation lifecycle, when API initiated.
    - `transactionHash` string: Durable deployment transaction hash, when prepared.
    - `pendingOperation` object: Unresolved or terminally failed deployment operation for this agreement, in the same shape input records use for their on-chain operation data. Present while a permit deployment is in flight or after it failed terminally; cleared when the deployment completes. Poll the agreement to follow a pending deployment instead of re-submitting the permit.
      - `kind` 'deployment', required
      - `submissionId` string, required: Durable permit-operation identity (the same axis as an input submissionId).
      - `operationLifecycle` 'intent_recorded' | 'transaction_ready' | 'confirmed' | 'completed' | 'failed', required
      - `txHash` string
      - `blockNumber` integer
      - `error` string: Terminal failure classification, e.g. 'transaction_reverted'.
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `address` string: Deployed agreement address, when deployed.
    - `chainId` integer, required: Chain ID for the deployed agreement.
    - `status` 'Draft' | 'Deployed', required: Agreement record status.
    - `lastInputId` string: Most recent submitted input ID, when available.
    - `lastInputAt` string, date-time: Time of the most recent submitted input, when available.
    - `json` object, required: Authored agreement JSON.
    - `state` string: Cached agreement state, when available.
    - `variables` object: Current stored agreement values.
    - `updatedAt` string, date-time, required: Record update timestamp.
    - `createdAt` string, date-time, required: Record creation timestamp.
    - `displayName` string, required: Human-readable record label.
    - `owner` string: Wallet address associated with hosted record ownership.
    - `documentId` string: Opaque hosted agreement document identifier used by /agreements/documents/{documentId}.
    - `docUri` string: Optional document URI associated with the deployed agreement, typically /agreements/documents/{documentId}.
    - `contributors` string[]: Wallet addresses associated with agreement activity.
    - `participants` ParticipantRecord[]: Participants associated with agreement participant variables.
      - `variableKey` string, required: Participant address variable key in the agreement JSON.
      - `email` string, email: Participant email context.
      - `firstName` string: Participant first name, when available.
      - `lastName` string: Participant last name, when available.
      - `walletAddress` string: Participant wallet address, when available.
      - `walletBinding` 'verified_via_auth' | 'verified_via_siwe' | 'partner_asserted': Wallet provenance recorded by the API.
    - `observers` string[]: Observer email addresses associated with the agreement record.
    - `onChain` object: On-chain agreement data when available.
  - `meta` ResponseMeta, required
    - `apiVersion` string, required
    - `requestId` string, required: Correlation ID for support and debugging.

## Other responses

- `400`: Invalid deployment request.
- `401`: Missing or invalid API credential.
- `402`: The authenticated Shodai account has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.
- `403`: The credential lacks the required OAuth scope, the account lacks entitlement, or the account cannot access the resource.

---

[API](https://skmtc.dev/shodai/apis/agreements-api.md) · [All operations](https://skmtc.dev/shodai/apis/agreements-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shodai/apis/agreements-api/revisions/0ac329d0e9a0?raw)