KeeperHub Chains API

openapi: 3.2.0
info:
  title: KeeperHub Chains API
  version: 1.0.0
  description: Web3 workflow automation platform. Workflows are callable by AI agents via REST or MCP.
  x-guidance: 'KeeperHub exposes workflows as REST endpoints under /api/mcp/workflows/{slug}/call.

    Each workflow has a slug, accepts a JSON body, and returns a JSON response with `executionId`, `status`, and `output`.

    Auth: paid workflows return HTTP 402 with x402/MPP payment info on the first call; pay (e.g. via agentcash, openclaw, or any x402 client) and replay. Free workflows can be called directly.

    Categories of workflows include: DeFi yield/risk reads (e.g. usdc-yield-rates-aave-vs-compound, aave-v3-health-check, defi-risk-snapshot), tipping primitives (microtip), and write-type workflows that return unsigned calldata for the caller to sign and broadcast.


    ## Worked examples


    ### Example 1: Compare USDC yield (paid, $0.01)

    POST /api/mcp/workflows/usdc-yield-rates-aave-vs-compound/call

    Body: {}

    Response (after payment): { executionId, status: "success", output: { result: { rates: [...], bestRate, bestProtocol } } }


    ### Example 2: Aave v3 health check (paid, $0.01)

    POST /api/mcp/workflows/aave-v3-health-check/call

    Body: { "address": "0x..." }

    Response (after payment): { executionId, status: "success", output: { result: { healthFactor, totalCollateralUSD, totalDebtUSD, riskLevel } } }


    ### Example 3: Discover available workflows (free)

    GET /api/mcp/workflows  (returns the list of all listed workflows + pricing)

    GET /openapi.json       (this document; full schema for every workflow)


    When in doubt, fetch /openapi.json and read the per-workflow `x-payment-info`, `security`, and `requestBody` fields.


    ## Errors, versioning, and rate limits


    Every failure returns the same envelope: `{ error, detail, hint?, docs?, request_id }`. Branch on `error` (a stable snake_case code) and never on `detail`. See `components.schemas.Error` and `x-error-model`.

    Pin a call to a version with the `KeeperHub-Version: 1` request header; omit it to track the current version. Breaking changes ship as a new version, announced with `Deprecation` and `Sunset` headers at least 180 days apart. See `x-api-versioning`.

    Limited endpoints return `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (delta seconds), plus the legacy `X-RateLimit-*` spellings, and `Retry-After` on a 429. Self-throttle from those rather than backing off blindly.'
servers:
- url: https://app.keeperhub.com
tags:
- name: Chains
paths:
  /api/chains:
    get:
      operationId: list-chains
      summary: Supported chains
      description: 'The live source of truth for supported chains, including each chain''s support status. Public: answers whether or not a credential is supplied, so it tests reachability rather than a credential.'
      security: []
      parameters:
      - name: KeeperHub-Version
        in: header
        required: false
        description: Pins the request to a major version of the REST surface. Omit to use the current version. A breaking change ships as a new version rather than in place, so a pinned caller keeps its behaviour.
        schema:
          type: string
          enum:
          - '1'
          default: '1'
      responses:
        '200':
          description: Supported chains and their status.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Chains
components:
  responses:
    Unauthorized:
      description: The credential is missing, malformed, or revoked. `error` is `unauthorized`.
      headers:
        x-request-id:
          description: Correlation id, matching request_id in the body.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The route or the resource does not exist. `error` is `not_found`.
      headers:
        x-request-id:
          description: Correlation id, matching request_id in the body.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidInput:
      description: The request body or query failed validation. `error` is `invalid_input`.
      headers:
        x-request-id:
          description: Correlation id, matching request_id in the body.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: An unexpected server fault. `error` is `internal_error`. Retry with backoff and quote `request_id` if it persists.
      headers:
        x-request-id:
          description: Correlation id, matching request_id in the body.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: A published rate limit was exceeded. `error` is `rate_limited`. Wait for `Retry-After` seconds before retrying.
      headers:
        x-request-id:
          description: Correlation id, matching request_id in the body.
          schema:
            type: string
        RateLimit-Limit:
          description: Requests permitted in the current window.
          schema:
            type: integer
        RateLimit-Remaining:
          description: Requests left in the current window.
          schema:
            type: integer
        RateLimit-Reset:
          description: Seconds until the current window resets.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Legacy spelling of RateLimit-Limit.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Legacy spelling of RateLimit-Remaining.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Legacy spelling. Unix epoch seconds at which the window resets - an absolute time, not a delta.
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientScope:
      description: The credential is valid but not permitted for this operation. `error` is `insufficient_scope`.
      headers:
        x-request-id:
          description: Correlation id, matching request_id in the body.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      - detail
      properties:
        error:
          type: string
          description: Stable snake_case error code. Branch on this value; it does not change across releases.
          examples:
          - rate_limited
        detail:
          type: string
          description: Human-readable explanation. Wording is not stable - never parse it.
        hint:
          type: string
          description: Suggested next step for the caller, when one exists.
        docs:
          type: string
          format: uri
          description: Deep link to the relevant documentation, when one exists.
        request_id:
          type: string
          description: Correlation id, echoed on the x-request-id response header. Quote it in support requests.
  securitySchemes:
    x402:
      type: http
      scheme: Payment
      description: x402 challenge-response payment. The first unpaid call returns HTTP 402 with payment requirements; the client signs that payment and replays the request.
    siwx:
      type: http
      scheme: bearer
      bearerFormat: CAIP-122
      description: Sign-In with X identity proof (CAIP-122) for compatible agent clients. KeeperHub workflow calls primarily use x402 payment discovery today.
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An organization API key (prefix `kh_`) or an OAuth access token, sent as `Authorization: Bearer <token>`. Create an organization key from the API Keys screen; verify it with GET /api/keys.'
x-api-versioning:
  current: '1'
  strategy: header
  header: KeeperHub-Version
  supported:
  - '1'
  policy: Additive changes (new endpoints, new optional fields, new enum members) ship inside the current version. Breaking changes ship as a new version and never in place.
  deprecation:
    headers:
    - Deprecation
    - Sunset
    - Link
    deprecationHeader: RFC 9745. Present once an endpoint, a version, or one accepted request shape is deprecated; carries the date the deprecation took effect as a Structured Fields Date - an "@" sigil followed by integer seconds since the Unix epoch, e.g. "@1789516800". Not an HTTP-date; Sunset is.
    sunsetHeader: RFC 8594. The earliest date the deprecated thing may stop being accepted, as an HTTP-date. Where an endpoint or a version is deprecated, that is the date it may stop answering. Where only one accepted request shape is deprecated, the endpoint keeps answering and the shape stops being accepted; the Link target says which case applies.
    linkHeader: 'Link: <url>; rel="deprecation" points at the migration note.'
    minimumNoticeDays: 180
x-error-model:
  mediaType: application/json
  schema: '#/components/schemas/Error'
  codeField: error
  messageField: detail
  correlationField: request_id
  correlationHeader: x-request-id
  codes:
  - unauthorized
  - insufficient_scope
  - not_found
  - invalid_input
  - conflict
  - rate_limited
  - internal_error
x-rate-limits:
  headers:
  - RateLimit-Limit
  - RateLimit-Remaining
  - RateLimit-Reset
  - X-RateLimit-Limit
  - X-RateLimit-Remaining
  - X-RateLimit-Reset
  retryAfterHeader: Retry-After
  pollIntervalHeader: X-Poll-Interval-Hint
  pollIntervalBodyField: pollIntervalHint
  documented: https://docs.keeperhub.com/api/errors
x-service-info:
  categories:
  - web3
  - automation
  - blockchain
  docs:
    homepage: https://docs.keeperhub.com
  developerPortal: https://docs.keeperhub.com/platform-reference
  errors: https://docs.keeperhub.com/api/errors
  mcp:
    card: https://app.keeperhub.com/.well-known/mcp.json
    endpoint: https://app.keeperhub.com/mcp
    publicEndpoint: https://app.keeperhub.com/mcp/public
    transport: streamable-http
  cli:
    name: kh
    install: brew install keeperhub/tap/kh
    docs: https://docs.keeperhub.com/cli/quickstart
  sandbox:
    testnets:
    - name: Ethereum Sepolia
      chainId: 11155111
    - name: Base Sepolia
      chainId: 84532
    simulation: 'Direct-execution tools accept simulate: true, which reports whether a transaction would revert without broadcasting it. EVM chains only.'
    docs: https://docs.keeperhub.com/platform-reference