What Agents Buy

USE WHEN you need an API that does something and want payable options. Searches the whole x402 market for what you describe and returns a ranked, pre-vetted shortlist, proven-accurate sellers first, then payment-safety, then price. Covers every reachable endpoint, not just ones we have bought from. Next step: check_before_paying on your pick, then read the payTo from the live 402 and sign against it.

{
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "description": "What you need, in words or keywords, e.g. 'validate an email address', 'BTC price', 'geocode an address'"
    },
    "max_price_usdc": {
      "type": "number",
      "description": "Optional ceiling on the per-call price in USDC"
    },
    "min_reliability": {
      "type": "integer",
      "description": "Optional floor on the reliability score 0-100 (default 0 = no floor; the whole reachable market)"
    },
    "limit": {
      "type": "integer",
      "description": "How many results (default 8, max 25)"
    },
    "allowed_verdicts": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "CLEAR",
          "HOLD",
          "ABORT",
          "UNRATED"
        ]
      },
      "description": "Optional policy filter: only return sellers whose current preflight verdict is in this list, e.g. [\"CLEAR\"]. Default: no filter, every result carries its verdict so you can decide."
    }
  },
  "required": [
    "task"
  ]
}

USE WHEN your agent is about to pay an x402 API and you want to know if it is safe and worth it. Returns one verdict for a URL or host in the `verdict` field (gate on that; `light` is the same decision as a colour, for display): CLEAR (nothing alarming), HOLD (pay but resolve the reasons), ABORT (do not pay without checking the live 402), UNRATED (no data). Also returns a confidence tier (verified = a payment to this seller settled AND produced a gradeable result, checked = free probe measured) and its payment history. Folds live price and payTo honesty, phantom paywalls, delivery receipts, and the wash/real-demand read into that one light. Pass detail:true for the full read. Whatever it says, still read the payTo and amount out of the live 402 and sign against those. (Formerly named preflight.)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL or bare hostname, e.g. https://blockrun.ai/api/v1/exa/search or blockrun.ai"
    },
    "detail": {
      "type": "boolean",
      "description": "Include the full payment-safety detail (live-402 honesty, demand shape, grades). Default false."
    }
  },
  "required": [
    "url"
  ]
}

USE WHEN you have a specific seller host and want its full track record. Returns every grade earned by actually paying it, what was quoted versus charged, whether goods arrived, its settlement volume, and its Organic Demand Score with the demand-shape read (is the volume real independent demand, or one wallet supplying almost all of it). The deep dossier on one seller; for a quick go/no-go before paying, use check_before_paying instead. (Formerly named get_service.)

{
  "type": "object",
  "properties": {
    "host": {
      "type": "string",
      "description": "Hostname, e.g. blockrun.ai or api.bitrefill.com"
    }
  },
  "required": [
    "host"
  ]
}

USE WHEN you want a ranked list of sellers across the market. by='revenue' ranks by raw USDC received (who is busy); by='real_demand' ranks by Organic Demand Score (whose money comes from many independent wallets rather than one wallet supplying almost all of it). The two disagree often, and the disagreement is the point. For accuracy ranking within an objective category, use rank_by_accuracy. (Formerly named top_services.)

{
  "type": "object",
  "properties": {
    "by": {
      "type": "string",
      "enum": [
        "revenue",
        "real_demand"
      ],
      "default": "revenue"
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 50
    }
  }
}

USE WHEN a category has an objective right answer (crypto-price, stock-price, fx-rate, gas-price, wallet-balance, weather) and you want the sellers we PAID ranked by how close their returned value was to a primary source that cannot be a reseller (exchange median, chain balanceOf, ECB rates, FMP quote). Top rows are the cheapest accurate sellers. Call with no category to list the available ones. (Formerly named most_accurate.)

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "One of: crypto-price, stock-price, fx-rate, gas-price, wallet-balance, weather. Omit to list categories."
    },
    "limit": {
      "type": "integer",
      "description": "How many results (default 10, max 50)"
    }
  }
}

USE WHEN asked how big x402 is, whether it is growing, or what settled recently. Returns both what actually settled on Base over the last day (from chain logs, per tracked seller) and the live market pulse (24h volume and payments with day-over-day change, a 7-day series, and stablecoin circulation). All measured from chain, not registry counters, which are not demand and can be bought. (Merges the former market_summary and market_pulse.)

{
  "type": "object",
  "properties": {}
}

USE WHEN writing payment code, or before trusting an unfamiliar seller. The field notes: each is a specific way an agent paying an API loses money or is misled, what it cost to learn, and what to do instead. (Formerly named list_traps.)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Optional filter, e.g. 'price', 'delivery'"
    }
  }
}