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

# Get agreement state

> Returns the current state of an agreement. For deployed agreements, interpret the state against the authored agreement lifecycle.

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

Use the current state together with the authored agreement lifecycle before choosing an input to submit.


## OpenAPI

````yaml /openapi.json get /v0/agreements/{id}/state
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/{id}/state:
    get:
      tags:
        - Using Agreements
      summary: Get agreement state
      description: >-
        Returns the current state of an agreement. For deployed agreements,
        interpret the state against the authored agreement lifecycle.
      operationId: getAgreementState
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Agreement ID or deployed agreement address.
      responses:
        '200':
          description: Agreement state payload.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/AgreementStateResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                state:
                  summary: Current agreement state
                  value:
                    data:
                      status: Deployed
                      state: AWAITING_PAYMENT
                    meta:
                      apiVersion: v0
                      requestId: req_123
        '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'
        '404':
          description: Agreement not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: const state = await client.getAgreementState('agr_123');
components:
  schemas:
    AgreementStateResponse:
      type: object
      required:
        - status
        - state
      properties:
        status:
          type: string
          enum:
            - Draft
            - Deployed
          description: Agreement record status.
        state:
          oneOf:
            - type: string
            - type: 'null'
          description: Current agreement state, or null when no state is available.
      description: Current agreement status and state.
      example:
        status: Deployed
        state: AWAITING_PAYMENT
    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.
  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

````