API Evangelist enhancements for the Figment API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Figment API
  version: 1.0.0
extends: openapi/figment-api-openapi-original.yml
x-generated: '2026-08-04'
x-method: generated
x-source: >-
  Enhancements derived from Figment's own published documentation (Authentication, Pagination,
  Idempotency Requests, Getting Started) applied over the verbatim OpenAPI 3.1.0 harvested from
  https://api.figment.io/openapi/figment-api.yaml. The original spec is never mutated. Every value
  below is documented by Figment; nothing here is invented.
actions:
- target: $.info
  description: Provenance and API Evangelist artifact cross-links.
  update:
    x-apievangelist-provider: figment
    x-apievangelist-harvested: '2026-08-04'
    x-apievangelist-source: https://api.figment.io/openapi/figment-api.yaml
    x-apievangelist-artifacts:
      authentication: authentication/figment-authentication.yml
      conventions: conventions/figment-conventions.yml
      errors: errors/figment-problem-types.yml
      lifecycle: lifecycle/figment-lifecycle.yml
      rate_limits: rate-limits/figment-rate-limits.yml
      data_model: data-model/figment-data-model.yml
      sandbox: sandbox/figment-sandbox.yml
      conformance: conformance/figment-conformance.yml
      skills: skills/_index.yml
- target: $.info
  description: >-
    Add a description to info — the published spec carries only title, version and termsOfService.
  update:
    description: >-
      Unified REST API for institutional staking across proof-of-stake networks. Build ready-to-sign
      staking, delegation, undelegation, withdrawal, exit, compound and consolidation transactions,
      broadcast signed payloads, and read back validators, stakes, activities, balances, rewards,
      reward rates, statements and portfolio data. Figment never holds customer keys — write
      operations return an unsigned transaction that the caller signs in its own custody and posts
      back to the relevant /broadcast endpoint.
    contact:
      name: Figment
      url: https://www.figment.io/company/meet-with-us/
- target: $.components
  description: >-
    Declare the API key security scheme Figment documents but does not express in the spec. The
    published document has no components.securitySchemes at all, so generated clients and agents
    cannot discover how to authenticate from the contract alone.
  update:
    securitySchemes:
      ApiKeyAuth:
        type: apiKey
        in: header
        name: x-api-key
        description: >-
          Organization API key issued in the Developers section of https://app.figment.io/. Carries a
          permission (Read/Write or Read-Only) and an environment (test or production). Read-Only keys
          are rejected on create-validators and exit-validators; test keys work only against testnets
          and devnets, production keys only against mainnets. Source:
          https://docs.figment.io/reference/authentication
- target: $
  description: Apply the API key requirement globally, as the documentation states.
  update:
    security:
    - ApiKeyAuth: []
- target: $
  description: >-
    Record the documented rate limits at the document level. Figment publishes 200 req/s and
    3500 req/min in Getting Started but signals nothing in the spec or in response headers.
  update:
    x-rate-limits:
    - limit: 200
      window: 1s
      scope: api-key
    - limit: 3500
      window: 60s
      scope: api-key
    x-rate-limit-headers: none-published
    x-rate-limit-source: https://docs.figment.io/reference/getting-started-1
- target: $
  description: >-
    Record the documented pagination contract at the document level so agents do not have to infer it
    per operation.
  update:
    x-pagination:
      style: page-based
      request_params: ['page[number]', 'page[size]']
      body_form: '{"page": {"number": 2, "size": 10}}'
      default_size: 50
      max_size: 100
      response_envelope: meta.pagination
      response_fields: [current_page, total_pages, total_item_count]
      source: https://docs.figment.io/reference/pagination
- target: $.paths['/ethereum/validators'].post
  description: >-
    Declare the documented idempotency header and the 409 conflict response on the standard Ethereum
    validator provisioning operation. Both are specified on
    https://docs.figment.io/reference/idempotency-requests but absent from the contract.
  update:
    parameters:
    - name: X-Figment-Idempotency-Key
      in: header
      required: false
      description: >-
        Unique key (UUID v4 recommended) per logical provisioning operation, stable across retries.
        Same key + same body returns the cached response without re-provisioning; same key + a
        different body returns 409; a retry while the original is in flight returns 409. Only 2xx
        responses are cached — on a 4xx/5xx the key is released and the same key may be reused.
      schema:
        type: string
        format: uuid
    responses:
      '409':
        description: >-
          Idempotency conflict — either the idempotency key was replayed with a different request
          body (fingerprint mismatch) or the original request is still being processed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/error'
- target: $.paths['/ethereum/validators/0x02'].post
  description: >-
    Same idempotency declaration for Pectra / 0x02 compounding-credential validator provisioning.
  update:
    parameters:
    - name: X-Figment-Idempotency-Key
      in: header
      required: false
      description: >-
        Unique key (UUID v4 recommended) per logical provisioning operation, stable across retries.
        See https://docs.figment.io/reference/idempotency-requests
      schema:
        type: string
        format: uuid
    responses:
      '409':
        description: >-
          Idempotency conflict — key replayed with a different body, or the original request is still
          in flight.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/error'
- target: $.paths['/injective/transactions/broadcast'].post
  description: >-
    Supply the missing operationId. This operation ships with no operationId, so it cannot be
    referenced by generated clients, Arazzo steps or MCP tool bindings.
  update:
    operationId: broadcast-injective-tx
    x-apievangelist-note: operationId added by overlay — absent in the published spec.
- target: $.paths['/x402/supported'].get
  description: Supply the missing operationId for the x402 facilitator supported-kinds endpoint.
  update:
    operationId: x402-supported
    x-apievangelist-note: operationId added by overlay — absent in the published spec.
- target: $.paths['/x402/verify'].post
  description: Supply the missing operationId for the x402 verify endpoint.
  update:
    operationId: x402-verify
    x-apievangelist-note: operationId added by overlay — absent in the published spec.
- target: $.paths['/x402/settle'].post
  description: Supply the missing operationId for the x402 settle endpoint.
  update:
    operationId: x402-settle
    x-apievangelist-note: operationId added by overlay — absent in the published spec.
- target: $.paths['/x402/partner_analytics'].get
  description: Supply the missing operationId for the x402 partner analytics endpoint.
  update:
    operationId: x402-partner-analytics
    x-apievangelist-note: operationId added by overlay — absent in the published spec.
- target: $.paths['/x402/settlement_reports'].get
  description: Supply the missing operationId for the x402 settlement reports endpoint.
  update:
    operationId: x402-settlement-reports
    x-apievangelist-note: operationId added by overlay — absent in the published spec.