P0 Agent Economy Index Kv API

openapi: 3.2.0
info:
  title: P0 Agent Economy Index Kv API
  version: 0.2.0
  x-logo:
    url: https://x402-bazaar-rank.x402-bazaar-rank-worker.workers.dev/icon.png
  contact:
    name: dev Mike (P0)
    email: chebotarev.mike@gmail.com
    url: https://x402-bazaar-rank.x402-bazaar-rank-worker.workers.dev/join
  description: 'An open index of the machine-to-machine (agent) economy. x402 routes: ranked discovery over the live x402 service market, every indexed service scored by real 30-day calls and paying-wallet bounds, with a receipt naming the snapshot hash and scoring revision. /economy routes, for Tempo MPP, Virtuals ACP, Olas, Masumi, ERC-8004 agent registries, Solana agent registries, Base agent contracts and MCP servers (Official MCP Registry): each protocol''s published figures (agent or server counts, transactions or payment events; payers and USD volume only where the source publishes them: payers for x402 and Tempo MPP, USD volume for x402 and Virtuals ACP), each with its unit, window and source; units differ, so totals are not summed. L402 and per-service MPP listings are not covered.'
  x-guidance: 'Market data over 25897 listed x402 services, 30-day window. For protocols beyond x402 (Tempo MPP, Virtuals ACP, Olas, Masumi, ERC-8004 agent registries, Solana agent registries, Base agent contracts and MCP servers (Official MCP Registry)) use /economy, /economy/protocols and /economy/search. For x402, start with GET /search?q=<capability> for ranked services, or /top for the highest-demand ones with callsPerPayer (near 1 means each payer bought once, high means repeat use). /price benchmarks what comparable services charge, /networks breaks demand down by chain, /tags is the capability vocabulary, /count is the market totals, /service looks one service up by URL, /report and /alpha are the category report and the underserved niches, /dataset is the full export. Premium: /dataset/pro ($25) is the enriched full export (demand rank overall and within the top tag, per-seller and per-category aggregates) and /report/weekly ($5) the market report; /dataset/teaser is a free 5% sample in the /dataset/pro row schema. EVERY paid route answers a call with no parameters at all with real data rather than an error, so a blind purchase is never wasted. If you transferred the price to payTo in USDC, USDT or DAI on Base without a payment header, just call the route again within 30 minutes and it serves the data (one transfer, one response); other transfers are never matched automatically: claim them with ?tx=<hash> (on /pay/check use ?payment_tx=<hash> instead, since its tx is the transaction being checked) on Base, Ethereum, Arbitrum or Polygon (USDC, USDT, DAI, WETH, cbBTC, WBTC, USDT0 where that chain has the token, or native ETH/POL), ?btc=<txid> (BTC), ?sol=<signature> (SOL, USDC, USDT), ?tron=<txid> (TRX, USDT TRC-20) or ?stx=<txid> (STX, sBTC); a direct transfer on any other chain, or of a token not named here, cannot be claimed. The two premium routes are the exception and serve a plain transfer only when it is claimed with ?tx=<hash>. /sample, /health and /dataset/teaser are free. Payment is x402 v2, scheme exact, networks eip155:8453, eip155:42161, eip155:137 (USDC); stacks:1 (sBTC); eip155:43114, eip155:10, eip155:42220 (USDC via UltravioletaDAO); eip155:42161 (USDT0), eip155:1 (USDC) via UltravioletaDAO, or MPP (method evm, intent charge, USDC on EVM networks, same prices); a plain transfer on Base, Ethereum, Arbitrum or Polygon also works via ?tx=<hash>.'
servers:
- url: https://x402-bazaar-rank.x402-bazaar-rank-worker.workers.dev
tags:
- name: Kv
paths:
  /kv/put:
    post:
      summary: 'Use when an agent needs memory between runs without an account: store value…'
      operationId: kv_put
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - value
              properties:
                key:
                  type: string
                  pattern: ^[A-Za-z0-9._:/-]{1,128}$
                  description: 'Key, 1-128 characters from A-Z a-z 0-9 . _ : / -'
                value:
                  type:
                  - string
                  - object
                  - array
                  - number
                  - boolean
                  description: Text, or JSON stored as text (max 8 KB)
                ttl:
                  type: integer
                  minimum: 60
                  maximum: 7776000
                  default: 2592000
                  description: Seconds to keep the key
            example:
              key: session/last-run
              value:
                step: 3
                cursor: abc
              ttl: 86400
      security:
      - x402: []
      - mpp: []
      x-payment-info:
        protocols:
        - x402: {}
        - mpp:
            method: evm
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        network: eip155:8453
        networks: eip155:8453, eip155:42161, eip155:137 (USDC); stacks:1 (sBTC); eip155:43114, eip155:10, eip155:42220 (USDC via UltravioletaDAO); eip155:42161 (USDT0), eip155:1 (USDC) via UltravioletaDAO
        asset: USDC
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        alternatives:
        - assets: USDC, USDT, DAI, ETH, WETH, cbBTC, WBTC
          networks: Base, Ethereum, Polygon, Arbitrum
          address: '0xECa891e34b3E5873181Fb779672564E198C55354'
        - assets: BTC
          networks: Bitcoin
          address: bc1qqwgyyqv6raq2jnghals2n2aujgwd4e9p64g4hr
        - assets: SOL, USDC, USDT
          networks: Solana
          address: FTbVqWwsfJJ5AuAwNDuCuzdpwCEJahu14HAUgAYcJHuq
        - assets: STX, sBTC
          networks: Stacks
          address: SP34GH04YTB01AMXF4CAQ10Y5B7G4E0119N99W986
        - assets: TRX, USDT (TRC20)
          networks: TRON
          address: TB9rHqT8yLxwdsWCb3zN2nvjc8wLhsUdaQ
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                required:
                - namespace
                - key
                - stored
                - bytes
                - stored_as
                - ttl_seconds
                - expires_at
                - as_of
                - note
                properties:
                  namespace:
                    type: string
                  key:
                    type: string
                  stored:
                    type: boolean
                  bytes:
                    type: number
                  stored_as:
                    type: string
                  ttl_seconds:
                    type: number
                  expires_at:
                    type: string
                  as_of:
                    type: string
                  note:
                    type: string
              example:
                namespace: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
                key: session/last-run
                stored: true
                bytes: 26
                stored_as: json
                ttl_seconds: 86400
                expires_at: '2026-10-20T12:00:00.000Z'
                as_of: '2026-10-19T12:00:00.000Z'
                note: 'Namespace = the wallet that paid for this call: only calls paid by the same wallet can read these keys. Stored in Cloudflare KV (eventually consistent, visible everywhere within about 60 s), plain text, not encrypted at the application level: do not store secrets. Expired keys disappear.'
        '402':
          description: x402 v2 payment required; nothing is charged when the input is refused
      tags:
      - Kv
  /kv/get:
    get:
      summary: 'Use when an agent needs a value it stored earlier with /kv/put: returns the…'
      operationId: kv_get
      parameters:
      - name: key
        in: query
        required: true
        description: 'Key, 1-128 characters from A-Z a-z 0-9 . _ : / -'
        schema:
          type: string
          pattern: ^[A-Za-z0-9._:/-]{1,128}$
        example: session/last-run
      security:
      - x402: []
      - mpp: []
      x-payment-info:
        protocols:
        - x402: {}
        - mpp:
            method: evm
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        network: eip155:8453
        networks: eip155:8453, eip155:42161, eip155:137 (USDC); stacks:1 (sBTC); eip155:43114, eip155:10, eip155:42220 (USDC via UltravioletaDAO); eip155:42161 (USDT0), eip155:1 (USDC) via UltravioletaDAO
        asset: USDC
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        alternatives:
        - assets: USDC, USDT, DAI, ETH, WETH, cbBTC, WBTC
          networks: Base, Ethereum, Polygon, Arbitrum
          address: '0xECa891e34b3E5873181Fb779672564E198C55354'
        - assets: BTC
          networks: Bitcoin
          address: bc1qqwgyyqv6raq2jnghals2n2aujgwd4e9p64g4hr
        - assets: SOL, USDC, USDT
          networks: Solana
          address: FTbVqWwsfJJ5AuAwNDuCuzdpwCEJahu14HAUgAYcJHuq
        - assets: STX, sBTC
          networks: Stacks
          address: SP34GH04YTB01AMXF4CAQ10Y5B7G4E0119N99W986
        - assets: TRX, USDT (TRC20)
          networks: TRON
          address: TB9rHqT8yLxwdsWCb3zN2nvjc8wLhsUdaQ
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                required:
                - namespace
                - key
                - found
                - value
                - json
                - stored_as
                - bytes
                - stored_at
                - expires_at
                - as_of
                - note
                properties:
                  namespace:
                    type: string
                  key:
                    type: string
                  found:
                    type: boolean
                  value:
                    type: string
                  json:
                    type: object
                    properties:
                      step:
                        type: number
                      cursor:
                        type: string
                  stored_as:
                    type: string
                  bytes:
                    type: number
                  stored_at:
                    type: string
                  expires_at:
                    type: string
                  as_of:
                    type: string
                  note:
                    type: string
              example:
                namespace: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
                key: session/last-run
                found: true
                value: '{"step":3,"cursor":"abc"}'
                json:
                  step: 3
                  cursor: abc
                stored_as: json
                bytes: 26
                stored_at: '2026-10-19T12:00:00.000Z'
                expires_at: '2026-10-20T12:00:00.000Z'
                as_of: '2026-10-19T12:00:00.000Z'
                note: 'Namespace = the wallet that paid for this call: only calls paid by the same wallet can read these keys. Stored in Cloudflare KV (eventually consistent, visible everywhere within about 60 s), plain text, not encrypted at the application level: do not store secrets. Expired keys disappear.'
        '402':
          description: x402 v2 payment required; nothing is charged when the input is refused
      tags:
      - Kv
  /kv/list:
    get:
      summary: 'Use when an agent needs to see what it has stored: lists up to 100 keys…'
      operationId: kv_list
      parameters:
      - name: prefix
        in: query
        required: false
        description: Only keys starting with this
        schema:
          type: string
          pattern: ^[A-Za-z0-9._:/-]{0,128}$
        example: session/
      - name: limit
        in: query
        required: false
        description: Keys per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        description: cursor from the previous page
        schema:
          type: string
      security:
      - x402: []
      - mpp: []
      x-payment-info:
        protocols:
        - x402: {}
        - mpp:
            method: evm
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        network: eip155:8453
        networks: eip155:8453, eip155:42161, eip155:137 (USDC); stacks:1 (sBTC); eip155:43114, eip155:10, eip155:42220 (USDC via UltravioletaDAO); eip155:42161 (USDT0), eip155:1 (USDC) via UltravioletaDAO
        asset: USDC
        price:
          mode: fixed
          currency: USD
          amount: '0.001'
        alternatives:
        - assets: USDC, USDT, DAI, ETH, WETH, cbBTC, WBTC
          networks: Base, Ethereum, Polygon, Arbitrum
          address: '0xECa891e34b3E5873181Fb779672564E198C55354'
        - assets: BTC
          networks: Bitcoin
          address: bc1qqwgyyqv6raq2jnghals2n2aujgwd4e9p64g4hr
        - assets: SOL, USDC, USDT
          networks: Solana
          address: FTbVqWwsfJJ5AuAwNDuCuzdpwCEJahu14HAUgAYcJHuq
        - assets: STX, sBTC
          networks: Stacks
          address: SP34GH04YTB01AMXF4CAQ10Y5B7G4E0119N99W986
        - assets: TRX, USDT (TRC20)
          networks: TRON
          address: TB9rHqT8yLxwdsWCb3zN2nvjc8wLhsUdaQ
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                required:
                - namespace
                - prefix
                - keys
                - count
                - list_complete
                - cursor
                - as_of
                - note
                properties:
                  namespace:
                    type: string
                  prefix:
                    type: string
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        bytes:
                          type: number
                        stored_as:
                          type: string
                        stored_at:
                          type: string
                        expires_at:
                          type: string
                  count:
                    type: number
                  list_complete:
                    type: boolean
                  cursor: {}
                  as_of:
                    type: string
                  note:
                    type: string
              example:
                namespace: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
                prefix: session/
                keys:
                - key: session/last-run
                  bytes: 26
                  stored_as: json
                  stored_at: '2026-10-19T12:00:00.000Z'
                  expires_at: '2026-10-20T12:00:00.000Z'
                count: 1
                list_complete: true
                cursor: null
                as_of: '2026-10-19T12:00:00.000Z'
                note: 'Namespace = the wallet that paid for this call: only calls paid by the same wallet can read these keys. Stored in Cloudflare KV (eventually consistent, visible everywhere within about 60 s), plain text, not encrypted at the application level: do not store secrets. Expired keys disappear.'
        '402':
          description: x402 v2 payment required; nothing is charged when the input is refused
      tags:
      - Kv
components:
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment signature; the 402 response tells how
    mpp:
      type: http
      scheme: Payment
      description: 'MPP (Machine Payments Protocol) credential, method evm, intent charge: the 402 WWW-Authenticate: Payment challenge tells how'
x-discovery:
  protocols:
  - x402
  - mpp
  network: eip155:8453
  networks: eip155:8453, eip155:42161, eip155:137 (USDC); stacks:1 (sBTC); eip155:43114, eip155:10, eip155:42220 (USDC via UltravioletaDAO); eip155:42161 (USDT0), eip155:1 (USDC) via UltravioletaDAO
  payTo: '0xECa891e34b3E5873181Fb779672564E198C55354'