satohub-ai Erc8004 API

openapi: 3.2.0
info:
  title: Sato Hub public Erc8004 API
  version: 1.1.0
  summary: Read access to the onchain agent library, its change feed, and the Agent Passport registry.
  description: 'Public reads need no key and no account; the projects and listings routes take a bearer key. A Sato API key is optional on every metered endpoint and only raises limits. What is free, what is paid (the plans are Sato Check Team and Platform & Data), every limit and the fee schedule are listed on the pricing page, and the same sheet is machine-readable at /api/pricing.json.


    Pricing: https://satohub.ai/pricing


    License: Catalog data CC-BY-4.0 — attribution: data by satohub.ai. Scores/liveness are informational signals, not safety or quality guarantees.


    Scores and liveness are informational signals computed from public evidence. They are not safety ratings, audits, or claims about returns. `verification_status` distinguishes self-reported from independently checked; self-reported is never presented as verified.


    Every shape this API returns is also published as a versioned JSON Schema (draft 2020-12) at https://satohub.ai/schemas — catalogue at https://satohub.ai/schemas/index.json. They are referenced from components.schemas below, and v1 is additive-only: a breaking change becomes v2 at a new URL. Validate with additional properties allowed.


    The same data is available to agents over MCP (Streamable HTTP, JSON-RPC) at https://satohub.ai/api/mcp — documented at https://satohub.ai/mcp. That endpoint is not described here because it is not REST.


    INTERPRETED ANSWERS. A route template sent literally (`{slug}`), an empty query or body, a parameter under another name (`?package=` for `?target=`) or another spelling of a chain (`8453`, `eth`, `bsc`) is answered with the closest honest thing instead of a bare 4xx, and always LABELLED: the body carries an `interpretation` object (`interpreted_as`, `requested`, `rule`, `note`; the same four keys are repeated at the top level when they cannot collide with the record''s own fields), and the response carries the header `X-Sato-Interpreted: ` (plus `Content-Location` when there is a canonical URL). An interpreted answer is never an exact match. Nothing that moves money is ever interpreted beyond a chain spelling: no amount, token, taker, recipient, deployer or slippage is defaulted, a missing chain is never assumed, a chain is never guessed from an address, and a generic network word (`mainnet`, `testnet`) is never read as a chain (the answer lists the candidates). Writes are never interpreted, and a receipt is never served for a template.'
  contact:
    name: Sato Hub
    url: https://satohub.ai
  x-guidance: 'Free: search and read the onchain-agent catalog (/api/export/index.json, /api/changes, /api/resolve) and use the MCP server at /api/mcp. Paid over x402 (USDC on Base, no account or key): GET /api/x402/history/{slug} for one listing''s daily Sato Score record, GET /api/x402/agent-economy for the weekly agent-economy series. Each paid read is priced per unit delivered (daily points or rows returned): the 402 states the exact amount, the unit, the quantity and the formula, which is also on /pricing. The Sato Score measures how open, active and verifiable a project is; it is not a safety or returns grade.'
  x-status:
    page: https://satohub.ai/status/sato-hub
    json: https://satohub.ai/api/status.json
    feed: https://satohub.ai/status/feed.xml
    note: Success ratios and latencies of Sato Hub's own hourly checks. Not a service-level agreement.
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://satohub.ai
security: []
tags:
- name: erc8004
  description: 'Per-agent ERC-8004 checks: what each registered agent declares and whether its declared endpoints answered Sato Hub''s daily check, plus the evidence documents behind Sato Hub''s onchain attestations. Readings on a date — never a judgement of safety or quality. Chains are never summed.'
paths:
  /api/export/erc8004-agents.json:
    get:
      tags:
      - erc8004
      operationId: getErc8004AgentsJson
      summary: Every ERC-8004 agent on a chain, with what it declares and whether it answered
      description: 'One row per agent id on the chain: owner, registration name, agentURI kind, whether the registration file resolved, the endpoint kinds and counts it DECLARES (mcp, a2a, x402, other), whether at least one declared endpoint answered Sato Hub''s latest check (`answering`; null = never checked, never false), the same restricted to checks dated `meta.as_of` (`answering_today`), the last check time, and the per-agent report URL. CC-BY-4.0. Declaring an endpoint is not running one, and a failed check may be the host, the network or us. The payload carries `meta { rules, coverage, next_update, as_of }`.'
      parameters:
      - name: chain
        in: query
        required: false
        schema:
          type: string
          enum:
          - celo
          default: celo
        description: Chain with per-agent daily checks. One chain per response; rows from different chains are never added.
      responses:
        '200':
          description: All rows for the chain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schema_version:
                    type: string
                  license:
                    type: string
                  chain:
                    type: string
                  chain_id:
                    type: integer
                  registry:
                    type: string
                  count:
                    type:
                    - integer
                    - 'null'
                    description: null when the table could not be read — unknown, not zero.
                  meta:
                    type: object
                  agents:
                    type: array
                    items:
                      type: object
                      properties:
                        chain:
                          type: string
                        agent_id:
                          type: string
                        owner:
                          type:
                          - string
                          - 'null'
                        name:
                          type:
                          - string
                          - 'null'
                        uri_kind:
                          type:
                          - string
                          - 'null'
                        resolved:
                          type:
                          - boolean
                          - 'null'
                        declared_kinds:
                          type: array
                          items:
                            type: string
                        declared_mcp:
                          type: integer
                        declared_a2a:
                          type: integer
                        declared_x402:
                          type: integer
                        declared_other:
                          type: integer
                        answering:
                          type:
                          - boolean
                          - 'null'
                        answering_today:
                          type:
                          - boolean
                          - 'null'
                        answering_endpoints:
                          type: integer
                        checked_endpoints:
                          type: integer
                        last_checked:
                          type:
                          - string
                          - 'null'
                        report_url:
                          type: string
                          format: uri
        '404':
          description: A chain without per-agent checks.
  /api/export/erc8004-agents.csv:
    get:
      tags:
      - erc8004
      operationId: getErc8004AgentsCsv
      summary: Every ERC-8004 agent on a chain, as CSV
      description: The same rows as erc8004-agents.json, one per line; declared_kinds is pipe-joined and an empty cell is unknown, never zero. CC-BY-4.0.
      parameters:
      - name: chain
        in: query
        required: false
        schema:
          type: string
          enum:
          - celo
          default: celo
        description: Chain with per-agent daily checks. One chain per response; rows from different chains are never added.
      responses:
        '200':
          description: CSV.
          content:
            text/csv:
              schema:
                type: string
        '404':
          description: A chain without per-agent checks.
  /api/erc8004/attestations/{id}:
    get:
      tags:
      - erc8004
      operationId: getErc8004AttestationEvidence
      summary: The evidence document behind one of Sato Hub's ERC-8004 reputation attestations
      description: The feedbackURI of an ERC-8004 Reputation `giveFeedback` Sato Hub posted. Returns the stored evidence bytes EXACTLY, so keccak256 of the response body equals the `feedbackHash` recorded on chain (also sent as the `X-Sato-Feedback-Hash` header and the ETag). Cached immutable once the attestation is confirmed. The document records a reading of Sato Hub's own probe — it is not a rating of the agent.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,15}$
        example: '1'
        description: Attestation id (decimal digits; the example shows the form).
      responses:
        '200':
          description: The evidence JSON, byte-for-byte.
          content:
            application/json:
              schema:
                type: object
        '404':
          description: No attestation with that id.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Two different credentials ride this header, and they are told apart by their shape.


        • A SATO API KEY, `sk_sato_…` — optional on every metered endpoint. It is NEVER required: each of those endpoints answers an anonymous caller at the free limits, and a key only raises the caps and attributes the calls to an account. A key may also be sent as `X-Sato-Key`. An unknown or revoked key is served as if no key were present, never refused. Limits and plans: /pricing.


        • A PRIVY ACCESS TOKEN for a signed-in account — required by the claim endpoints and the key-management endpoints. A token that is not a Sato key is treated as one of these.'
    satoKey:
      type: apiKey
      in: header
      name: X-Sato-Key
      description: 'The same optional Sato API key, on its own header. Equivalent to `Authorization: Bearer sk_sato_…`.'
externalDocs:
  description: The published Sato Hub formats, as JSON Schema.
  url: https://satohub.ai/schemas