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

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

For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).

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.


## OpenAPI

````yaml /openapi.json post /v0/agreements/deploy-with-permit
openapi: 3.1.0
info:
  title: Agreements API
  version: v0
  description: Author, deploy, read, and advance agreements through the Agreements API.
servers:
  - url: https://test-api.shodai.network
    description: Public base URL for the Agreements API testnet environment.
  - url: https://api.shodai.network
    description: Public base URL for the Agreements API production environment.
security: []
tags:
  - name: Agreement Records
    description: List and read agreement records.
  - name: Agreement Documents
    description: Resolve hosted agreement prose documents.
  - name: Authoring
    description: Check authored agreement JSON before deployment.
  - name: Deployment
    description: Preflight and deploy agreements.
  - name: Using Agreements
    description: Read state, inspect input history, and submit signed inputs.
  - name: System
    description: Health and OpenAPI discovery endpoints.
paths:
  /v0/agreements/deploy-with-permit:
    post:
      tags:
        - Deployment
      summary: Deploy agreement
      description: >-
        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.
      operationId: deployAgreementWithPermit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectDeployAgreementWithPermitRequest'
            examples:
              deployWithPermit:
                summary: Signed deployment request
                value:
                  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}

                        Service 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
      responses:
        '201':
          description: Deployed agreement record.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/AgreementRecord'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                deployedAgreement:
                  summary: Deployed agreement record
                  value:
                    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}

                            Service 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
        '400':
          description: Invalid deployment request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            The authenticated API principal has paid_required entitlement mode
            for the requested scope. Per-call x402 settlement is not
            implemented. Treat this as an entitlement/operator issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API key is not allowed to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: >-
            import { deployAgreementWithPermit } from
            '@cns-labs/agreements-api-client';


            const chainId = 59141;

            const validation = await client.validateDeployment({
              agreement,
              chainId,
              initValues,
              participants,
              observers,
            });


            const deployed = await deployAgreementWithPermit({
              client,
              walletClient,
              publicClient,
              chainId,
              agreement,
              displayName: 'Advisory Retainer',
              initValues: validation.variables,
              participants,
              observers,
            });
components:
  schemas:
    DirectDeployAgreementWithPermitRequest:
      type: object
      required:
        - agreement
        - displayName
        - chainId
        - signer
        - deadline
        - signature
      description: >-
        Deploys authored agreement JSON with deployment values, participant
        mappings, and an EIP-712 permit.
      properties:
        agreement:
          type: object
          additionalProperties: true
          description: Authored agreement JSON to deploy.
        displayName:
          type: string
          description: Human-readable label for the agreement record.
        docUri:
          type: string
          description: >-
            Optional document URI to associate with the deployed agreement. SDK
            helpers default this to /agreements/documents/{documentId}.
        documentId:
          type: string
          description: >-
            Opaque hosted document identifier associated with docUri. SDK
            helpers generate this when docUri is omitted.
        initValues:
          type: object
          additionalProperties: true
          description: >-
            Deployment values for variables required when the agreement is
            created.
        participants:
          type: array
          items:
            $ref: '#/components/schemas/DirectParticipantRecord'
          description: Participant wallet mappings for participant address variables.
        observers:
          type: array
          items:
            type: string
            format: email
          description: >-
            Optional observer email addresses to associate with the agreement
            record.
        chainId:
          type: integer
          description: >-
            Supported agreement deployment chain ID. Must match the chain used
            for deployment preflight, permit signing, and transaction
            submission.
        signer:
          type: string
          description: Wallet address that signed the EIP-712 deployment permit.
        deadline:
          type: integer
          description: Unix timestamp in seconds when the deployment permit expires.
        signature:
          $ref: '#/components/schemas/PermitSignature'
      example:
        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}

              Service 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'
    AgreementRecord:
      type: object
      required:
        - id
        - chainId
        - displayName
        - status
        - json
        - createdAt
        - updatedAt
      description: >-
        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.
      properties:
        id:
          type: string
          description: Agreement record ID.
        address:
          type: string
          description: Deployed agreement address, when deployed.
        chainId:
          type: integer
          description: Chain ID for the deployed agreement.
        status:
          type: string
          enum:
            - Draft
            - Deployed
          description: Agreement record status.
        lastInputId:
          type: string
          description: Most recent submitted input ID, when available.
        lastInputAt:
          type: string
          format: date-time
          description: Time of the most recent submitted input, when available.
        json:
          type: object
          additionalProperties: true
          description: Authored agreement JSON.
        state:
          type: string
          description: Cached agreement state, when available.
        variables:
          type: object
          additionalProperties: true
          description: Current stored agreement values.
        updatedAt:
          type: string
          format: date-time
          description: Record update timestamp.
        createdAt:
          type: string
          format: date-time
          description: Record creation timestamp.
        displayName:
          type: string
          description: Human-readable record label.
        owner:
          type: string
          description: Wallet address associated with hosted record ownership.
        documentId:
          type: string
          description: >-
            Opaque hosted agreement document identifier used by
            /agreements/documents/{documentId}.
        docUri:
          type: string
          description: >-
            Optional document URI associated with the deployed agreement,
            typically /agreements/documents/{documentId}.
        contributors:
          type: array
          items:
            type: string
          description: Wallet addresses associated with agreement activity.
        participants:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantRecord'
          description: Participants associated with agreement participant variables.
        observers:
          type: array
          items:
            type: string
            format: email
          description: Observer email addresses associated with the agreement record.
        onChain:
          type: object
          additionalProperties: true
          description: On-chain agreement data when available.
      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}

              Service 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'
    ResponseMeta:
      type: object
      required:
        - apiVersion
        - requestId
      properties:
        apiVersion:
          type: string
          example: v0
        requestId:
          type: string
          description: Correlation ID for support and debugging.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
              example: unauthorized
              description: Stable machine-readable error code.
            message:
              type: string
              example: Missing API key
              description: Safe human-readable error summary.
            details:
              description: Optional field errors or upstream-safe context.
            requestId:
              type: string
              description: Correlation ID for support and debugging.
    DirectParticipantRecord:
      type: object
      required:
        - variableKey
        - walletAddress
      properties:
        variableKey:
          type: string
          description: Participant address variable key in the agreement JSON.
        walletAddress:
          type: string
          description: >-
            Wallet address for this participant. Required for direct API
            deployment.
        email:
          type: string
          format: email
          description: Optional participant email context.
        firstName:
          type: string
          description: Optional participant first name.
        lastName:
          type: string
          description: Optional participant last name.
        walletBinding:
          type: string
          enum:
            - verified_via_auth
            - partner_asserted
          description: Wallet provenance recorded by the API.
      description: Participant mapping for direct API validation and deployment requests.
      example:
        variableKey: serviceProviderRepresentative
        walletAddress: '0x1111111111111111111111111111111111111111'
    PermitSignature:
      type: object
      required:
        - v
        - r
        - s
      description: EIP-712 signature parts.
      properties:
        v:
          type: integer
          description: Recovery identifier.
        r:
          type: string
          description: Signature r value.
        s:
          type: string
          description: Signature s value.
      example:
        v: 27
        r: '0x1111111111111111111111111111111111111111111111111111111111111111'
        s: '0x2222222222222222222222222222222222222222222222222222222222222222'
    ParticipantRecord:
      type: object
      required:
        - variableKey
      properties:
        variableKey:
          type: string
          description: Participant address variable key in the agreement JSON.
        email:
          type: string
          format: email
          description: Participant email context.
        firstName:
          type: string
          description: Participant first name, when available.
        lastName:
          type: string
          description: Participant last name, when available.
        walletAddress:
          type: string
          description: Participant wallet address, when available.
        walletBinding:
          type: string
          enum:
            - verified_via_auth
            - partner_asserted
          description: Wallet provenance recorded by the API.
        status:
          type: string
          enum:
            - pending
            - invited
            - accepted
          description: Participant invitation or acceptance status when available.
      example:
        variableKey: clientRepresentative
        email: client@example.com
        walletAddress: '0x2222222222222222222222222222222222222222'
        walletBinding: partner_asserted
        status: accepted
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        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.
      x-default: YOUR_API_KEY

````