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

# Preflight deployment request

> Checks whether authored agreement JSON plus target chain, deployment values, participant wallet mappings, and observer context are ready for deployment. This does not deploy the agreement.

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

This endpoint validates the assembled deployment context before any EIP-712 permit is signed. The `testnet` API environment supports Linea Sepolia, Ethereum Sepolia, and Base Sepolia; the `production` API environment supports Linea Mainnet and Base Mainnet. Include the target `chainId` so preflight, signing, and deploy-with-permit requests all use the same supported chain. In SDK integrations, prefer `client.validateDeployment(...)` before `deployAgreementWithPermit(...)`. 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/validate
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/validate:
    post:
      tags:
        - Deployment
      summary: Preflight deployment request
      description: >-
        Checks whether authored agreement JSON plus target chain, deployment
        values, participant wallet mappings, and observer context are ready for
        deployment. This does not deploy the agreement.
      operationId: validateAgreementDeployment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateDirectAgreementRequest'
            examples:
              deploymentPreflight:
                summary: Agreement plus deployment context
                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
                  chainId: 59141
                  initValues:
                    retainerTitle: Advisory Retainer
                  participants:
                    - variableKey: serviceProviderRepresentative
                      walletAddress: '0x1111111111111111111111111111111111111111'
                    - variableKey: clientRepresentative
                      walletAddress: '0x2222222222222222222222222222222222222222'
                      email: client@example.com
                  observers:
                    - legal@example.com
      responses:
        '201':
          description: Deployment preflight summary.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/ValidateDirectAgreementResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                ready:
                  summary: Deployment preflight summary
                  value:
                    data:
                      templateId: did:template:service-retainer-v0-1
                      participantVariableKeys:
                        - serviceProviderRepresentative
                        - clientRepresentative
                      participants:
                        - variableKey: serviceProviderRepresentative
                          walletAddress: '0x1111111111111111111111111111111111111111'
                        - variableKey: clientRepresentative
                          walletAddress: '0x2222222222222222222222222222222222222222'
                          email: client@example.com
                      observers:
                        - legal@example.com
                      variables:
                        serviceProviderRepresentative: '0x1111111111111111111111111111111111111111'
                        clientRepresentative: '0x2222222222222222222222222222222222222222'
                        retainerTitle: Advisory Retainer
                      contributors:
                        - '0x1111111111111111111111111111111111111111'
                        - '0x2222222222222222222222222222222222222222'
                      warnings: []
                    meta:
                      apiVersion: v0
                      requestId: req_123
        '400':
          description: Invalid deployment preflight payload.
          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: |-
            const validation = await client.validateDeployment({
              agreement,
              chainId: 59141,
              initValues,
              participants,
              observers,
            });

            console.log(validation.variables);
components:
  schemas:
    ValidateDirectAgreementRequest:
      type: object
      required:
        - agreement
        - chainId
      description: >-
        Deployment preflight request for authored agreement JSON and its
        deployment context.
      properties:
        agreement:
          type: object
          additionalProperties: true
          description: Authored agreement JSON to preflight before deployment.
        chainId:
          type: integer
          description: >-
            Supported agreement deployment chain ID to preflight. Use the same
            value when signing and submitting the deploy-with-permit request.
        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.
      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
        chainId: 59141
        initValues:
          retainerTitle: Advisory Retainer
        participants:
          - variableKey: serviceProviderRepresentative
            walletAddress: '0x1111111111111111111111111111111111111111'
          - variableKey: clientRepresentative
            walletAddress: '0x2222222222222222222222222222222222222222'
            email: client@example.com
        observers:
          - legal@example.com
    ValidateDirectAgreementResponse:
      type: object
      required:
        - templateId
        - participantVariableKeys
        - participants
        - observers
        - variables
        - contributors
        - warnings
      properties:
        templateId:
          oneOf:
            - type: string
            - type: 'null'
          description: Agreement metadata templateId or id value, when present.
        participantVariableKeys:
          type: array
          items:
            type: string
          description: Participant address variable keys found in the agreement JSON.
        participants:
          type: array
          items:
            $ref: '#/components/schemas/DirectParticipantRecord'
          description: Normalized participant wallet mappings.
        observers:
          type: array
          items:
            type: string
            format: email
          description: Normalized observer email addresses.
        variables:
          type: object
          additionalProperties: true
          description: Deployment values after participant wallet mappings are applied.
        contributors:
          type: array
          items:
            type: string
          description: >-
            Wallet addresses that may contribute to agreement visibility or
            activity.
        warnings:
          type: array
          items:
            type: string
          description: Warnings to review before deployment.
      example:
        templateId: did:template:service-retainer-v0-1
        participantVariableKeys:
          - serviceProviderRepresentative
          - clientRepresentative
        participants:
          - variableKey: serviceProviderRepresentative
            walletAddress: '0x1111111111111111111111111111111111111111'
          - variableKey: clientRepresentative
            walletAddress: '0x2222222222222222222222222222222222222222'
            email: client@example.com
        observers:
          - legal@example.com
        variables:
          serviceProviderRepresentative: '0x1111111111111111111111111111111111111111'
          clientRepresentative: '0x2222222222222222222222222222222222222222'
          retainerTitle: Advisory Retainer
        contributors:
          - '0x1111111111111111111111111111111111111111'
          - '0x2222222222222222222222222222222222222222'
        warnings: []
    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'
  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

````