Annalist Commerce API

openapi: 3.2.0
info:
  title: Annalist Dev Commerce API
  version: 0.9.0
  x-guidance: 'Annalist sells signed data for agents, priced per call over x402 (USDC on Base or Solana). Start with the free GET /v1/catalog: every paid route with the question it answers, its price and an example. Hyperliquid in one call: GET /v1/perp/full?coin=BTC (crowd state, smart-money positioning, liquidation levels). Before paying an x402 service: GET /v1/checks/service?host=, or the free GET /v1/verify/attestation?host=. Before connecting an MCP server: GET /v1/mcp/server?url=, or the free GET /v1/verify/mcp?url=. Before an agent shops on a site: the free GET /v1/verify/store?domain=, or GET /v1/web/readiness?domain=. Every answer is Ed25519-signed; the key is at /.well-known/annalist-key.json. Not investment advice.'
  description: 'Operations tagged commerce across 2 of this provider''s published API definitions: annalist-dev-openapi.json, openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.annalist.dev
tags:
- name: Commerce
paths:
  /v1/commerce/stores:
    get:
      operationId: commerce_stores
      tags:
      - Commerce
      summary: Which stores ship to my country, take my payment method and let an agent check…
      description: 'Stores from our weekly census of 65,000 top sites, filtered by what a shopping agent needs: ships to a country, UCP agent checkout and its capabilities, payment handlers (Google Pay, Shop Pay), currency, return window. Facts from each store''s own machine-readable files, never its policy pages. Most visited first. Signed.'
      x-price: $0.01
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.010000'
        protocols:
        - x402: {}
      parameters:
      - name: ships_to
        in: query
        required: false
        schema:
          type: string
          description: ISO country code the store ships to, for example US
      - name: capability
        in: query
        required: false
        schema:
          type: string
          description: UCP capability, for example checkout, cart, discount, order, catalog
      - name: payment
        in: query
        required: false
        schema:
          type: string
          description: payment handler, for example google.pay or shop_pay
      - name: currency
        in: query
        required: false
        schema:
          type: string
          description: ISO currency code, for example USD
      - name: agent_checkout
        in: query
        required: false
        schema:
          type: string
          description: 'ucp, acp or any: only stores with that agent checkout'
      - name: min_return_days
        in: query
        required: false
        schema:
          type: number
          description: only stores publishing a return window at least this long
      - name: platform
        in: query
        required: false
        schema:
          type: string
          description: shopify, magento, woocommerce...
      - name: limit
        in: query
        required: false
        schema:
          type: number
          description: 1 to 500, default 100
      responses:
        '200':
          description: Signed data
          content:
            application/json:
              schema:
                type: object
                required:
                - as_of
                - data
                - signature
                properties:
                  as_of:
                    type: string
                    format: date-time
                  data:
                    type: object
                  method:
                    type: object
                  request_id:
                    type: string
                  stale:
                    type: boolean
                  sources:
                    type: array
                    items:
                      type: string
                  notice:
                    type: string
                  key_id:
                    type: string
                  signature:
                    type: string
                    description: Ed25519 over RFC 8785 canonical JSON of {as_of, data, method, request_id}
                  signature_info:
                    type: string
              example:
                data:
                  count: 412
                  stores:
                  - domain: allbirds.com
                    ucp: '2026-08-25'
                    mcp_endpoint: https://weareallbirds.myshopify.com/api/ucp/mcp
                    capabilities:
                    - dev.ucp.shopping.checkout
                    payment_handlers:
                    - com.google.pay
                    currency: USD
                    ships_to:
                    - US
        '402':
          description: Payment required (x402 v2, USDC on Base or Solana)
    servers:
    - url: https://api.annalist.dev
x-refined-from:
- annalist-dev-openapi.json
- openapi.json