openapi: 3.0.3
info:
  title: API3 Signed Airnodes Signed Data API
  description: The API3 Signed API is a self-hosted REST service that stores and serves cryptographically signed oracle data produced by Airnode feed nodes. Airnode operators push signed beacon data to a Signed API instance; dApp developers and OEV searchers then pull that data off-chain for verification or to construct on-chain transactions. Each deployment is scoped to one or more Airnode addresses and exposes configurable public or auth-token-protected endpoints.
  version: 2.0.0
  contact:
    name: API3 DAO
    url: https://api3.org/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://signed-api.api3.org
  description: API3-hosted Signed API (example; operators self-host)
tags:
- name: Signed Data
  description: Reading and writing cryptographically signed oracle data
paths:
  /{airnodeAddress}:
    get:
      operationId: getSignedData
      summary: Get signed data for an Airnode
      description: Returns the latest signed beacon data for each templateId served by the given Airnode address. The response map is keyed by beaconId (the keccak256 hash of airnodeAddress and templateId). Callers may optionally provide an Authorization Bearer token if the endpoint requires it. Responses can omit signatures when the endpoint is configured with hideSignatures=true, and can include OEV-restricted data when isOev=true.
      tags:
      - Signed Data
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AirnodeAddress'
      responses:
        '200':
          description: Signed beacon data keyed by beaconId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedDataResponse'
              example:
                count: 3
                data:
                  '0xd6d5134a2b14b893c24ce4ef8f2b7543f02e59e5b2b8e9f3b1c0a4d5e6f7a8bc':
                    airnode: '0xA30CA71Ba54E83127214D3271aEA8F5D6bD4Dace'
                    templateId: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
                    beaconId: '0xd6d5134a2b14b893c24ce4ef8f2b7543f02e59e5b2b8e9f3b1c0a4d5e6f7a8bc'
                    timestamp: '1718227200'
                    encodedValue: '0x000000000000000000000000000000000000000000000004563918244f40000'
                    signature: 0xabcdef1234...
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: batchInsertSignedData
      summary: Batch insert signed data for an Airnode
      description: Allows an Airnode feed node to push a batch of freshly signed beacon data to this Signed API instance. Requires a valid Bearer token if the Airnode is access-controlled. The API accepts v1 and v2 signed-data payloads. Entries older than existing cached entries are silently skipped.
      tags:
      - Signed Data
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/AirnodeAddress'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInsertRequest'
            example:
            - airnode: '0xA30CA71Ba54E83127214D3271aEA8F5D6bD4Dace'
              templateId: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
              beaconId: '0xd6d5134a2b14b893c24ce4ef8f2b7543f02e59e5b2b8e9f3b1c0a4d5e6f7a8bc'
              timestamp: '1718227200'
              encodedValue: '0x000000000000000000000000000000000000000000000004563918244f40000'
              signature: 0xabcdef1234...
      responses:
        '201':
          description: Signed data accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchInsertResponse'
              example:
                count: 3
                skipped: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    BatchInsertRequest:
      type: array
      items:
        $ref: '#/components/schemas/SignedDataEntry'
      description: Array of signed data entries to insert (max 10 MB body)
    SignedDataResponse:
      type: object
      required:
      - count
      - data
      properties:
        count:
          type: integer
          description: Number of beacons returned
          example: 3
        data:
          $ref: '#/components/schemas/SignedDataMap'
    SignedDataEntry:
      type: object
      required:
      - airnode
      - templateId
      - beaconId
      - timestamp
      - encodedValue
      - signature
      properties:
        airnode:
          $ref: '#/components/schemas/EvmAddress'
          description: EVM address of the Airnode that produced and signed this data
        templateId:
          $ref: '#/components/schemas/EvmId'
          description: Identifier of the Airnode template (endpoint + parameters hash)
        beaconId:
          $ref: '#/components/schemas/EvmId'
          description: keccak256(airnodeAddress, templateId) — the on-chain beacon identifier
        timestamp:
          type: string
          description: Unix timestamp (seconds) when the value was signed
          example: '1718227200'
        encodedValue:
          type: string
          description: ABI-encoded int224 oracle value
          example: '0x000000000000000000000000000000000000000000000004563918244f40000'
        signature:
          type: string
          description: ECDSA signature by the Airnode private key over keccak256(templateId, timestamp, encodedValue). May be omitted when the endpoint is configured with hideSignatures=true.
          example: 0xabcdef1234567890...
    SignedDataMap:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/SignedDataEntry'
      description: Map of beaconId to the latest SignedDataEntry for that beacon
    EvmId:
      type: string
      pattern: ^0x[0-9a-fA-F]{64}$
      description: EVM 32-byte identifier as 66-char hex string (0x + 64 hex chars)
      example: '0xd6d5134a2b14b893c24ce4ef8f2b7543f02e59e5b2b8e9f3b1c0a4d5e6f7a8bc'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Unauthorized
    BatchInsertResponse:
      type: object
      required:
      - count
      - skipped
      properties:
        count:
          type: integer
          description: Number of entries accepted and stored
          example: 3
        skipped:
          type: integer
          description: Number of entries skipped because an equal or newer entry already exists in the cache for that beaconId
          example: 0
    EvmAddress:
      type: string
      pattern: ^0x[0-9a-fA-F]{40}$
      description: EVM checksummed address (42 hex characters with 0x prefix)
      example: '0xA30CA71Ba54E83127214D3271aEA8F5D6bD4Dace'
  responses:
    NotFound:
      description: Airnode address not found in this deployment
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Caller's Airnode address or token is not in the allowedAirnodes list
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid Bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    AirnodeAddress:
      name: airnodeAddress
      in: path
      required: true
      description: 'EVM-checksummed address of the Airnode whose data is being requested or pushed. Example: 0xA30CA71Ba54E83127214D3271aEA8F5D6bD4Dace.'
      schema:
        type: string
        pattern: ^0x[0-9a-fA-F]{40}$
        example: '0xA30CA71Ba54E83127214D3271aEA8F5D6bD4Dace'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token configured in the Signed API's allowedAirnodes or endpoint authTokens list. Required on endpoints or Airnode addresses configured with non-null authTokens.
externalDocs:
  description: API3 Documentation
  url: https://docs.api3.org/