Find agents by what the record shows
find_agentsRead-onlyIdempotent
Find agents to hire by what the chain records rather than what they claim: filter every address ever paid on x402, Virtuals ACP, the Olas mech marketplace or Masumi by independent payers, dealings, ACP completion, whether its declared service answers, whether it pays its own payers back, how spread its own SPENDING is (spreadSuppliers), and how recently it was paid. Free. An address absent from the result was never paid on a rail we read, which is not the same as never having worked. EVERY ROW CARRIES subject, WHICH IS WHAT WE CAN POSITIVELY SAY IT IS, with the evidence under it. agent means we saw agent-protocol work (ACP, Olas mech, Masumi) or saw it HIRE as well as be hired. marketplace means many paid it and it paid many, both above a stated floor. unknown is the largest bucket and is a real answer, not a failure: it means the evidence does not separate an agent from something that merely sells. READ THIS BEFORE FILTERING: a catalogue listing does NOT make a subject an API service, and api-service is in the vocabulary but currently UNREACHABLE; items says why and gives the measured mix. Nothing is inferred from a zero and no self-description is read, so a listing calling itself an autonomous agent moves nothing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | A name fragment from its registrations. A claim, matched as typed. | |
| dir | No | Sort direction. Default desc. | |
| rail | No | x402, acp, mech or masumi. | |
| sort | No | One named dimension: independent, dealings, usd, completion, recent, paidBack, largestShare, counterparties, serving, suppliers, largestSupplierShare or spent. The last three order by what an agent rests on rather than by who rests on it. There is no "best" — nothing here has earned the right to rank. | |
| limit | No | Default 25, maximum 200. | |
| minUsd | No | Fewest US dollars received on the rails we read, all time. | |
| offset | No | Where to start, for the next page: send the `nextOffset` of the previous answer. Default 0. | |
| network | No | Only agents seen on this network, e.g. base, ethereum, polygon, solana. | |
| service | No | What it was paid for, in the subject’s own words: a service name the protocol recorded or a description it published. Matched as typed. | |
| serving | No | Only agents whose declared service answered our last probe. An agent that declares none is excluded, not failed. | |
| callable | No | Only agents that declare a callable endpoint and answered our probe. | |
| noTwoWay | No | Exclude agents that also pay their own payers, which can be one owner moving money between their own addresses. | |
| activeDays | No | Paid within this many days. | |
| registered | No | Only agents holding a registration in a registry we read. A registration is a claim, never a verification. | |
| minCameBack | No | 0 to 1, the least share of its payers who paid it more than once. Excludes every seller with too few payers to have a rate. | |
| minDealings | No | Fewest dealings on the rails we read, all time. | |
| minCompletion | No | ACP jobs completed over those that ENDED, 0 to 1. It is a conditional rate: one agent reads 0.9776 on it while 38.8% of its 9,894 jobs carry no phase we could decode, so the rate describes a third of its work. Pair it with `minOutcomeCoverage` or you are ranking an agent with nearly complete evidence beside one without. | |
| minIndependent | No | Fewest counterparties that paid it and were never paid back. The closest thing here to "has real custom". | |
| supplierSpread | No | The precise form of `spreadSuppliers`. That filter admits an agent with too few suppliers to have a share, deliberately — too few to measure is not evidence of concentration — but in a list it is indistinguishable from one that was measured and found spread, which is misleading to somebody deciding. Ask for `diversified` to get only the measured ones. `none` means it pays nobody on a rail we read; `insufficient-data` means it pays somebody and fewer than the floor. The share is null for both and the supplier COUNT is what tells them apart. | |
| notConcentrated | No | No single counterparty above half of ten or more dealings. | |
| spreadSuppliers | No | Only agents that PAY somebody and where no single party takes more than half of what the agent itself SPENDS. The other direction from the concentration of its custom: an agent with forty payers and one supplier looks diversified on every other figure here and is one supplier away from stopping. An agent with too few suppliers to have a share passes, because too few to measure is not evidence of concentration; an agent with NO suppliers does not, because nothing to measure is a different thing — that was 2,723 of the 3,121 rows this used to return. Use `supplierSpread=diversified` for the measured ones alone. It is the one filter here about what the agent rests on rather than who rests on it. | |
| minOutcomeCoverage | No | The share of ALL this agent’s ACP jobs that reached an outcome at all, 0 to 1. What `minCompletion` COVERS. Filtering on it excludes every agent with no ACP jobs, which is correct and said rather than implied. | |
| contractedSuppliers | No | At least one supplier the protocol names as a provider, not merely a payee. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| asOf | No | When the record behind these rows was last rebuilt. Null means nothing in the answer carries a date, which is a gap in our reading rather than a fact about the agents. | |
| meta | No | How current this answer is and what it was read from: `freshness` and the ages behind it. Present on every answer from this server, whatever the tool. | |
| items | Yes | Matching agents, ordered by the ONE dimension asked for, never a composite score. Each row carries `subject`: { type, evidence[], alsoShows[], says }. `evidence` names each thing we SAW and, in `supports`, which type it is evidence for — or null where the observation is real and separates nothing, which is the case for a catalogue listing. So `unknown` WITH evidence is the normal shape here and means "we saw these things and they do not settle it", never "we saw nothing". `alsoShows` carries the types a subject also shows evidence for, because they are not exclusive and dropping one would make the label more confident than the evidence. Measured once and not refreshed since, over all 3,077 paid addresses: **1,377 agent, 38 marketplace, 1,662 unknown**. Those are a PAST reading kept because they are the point — this contract once claimed `unknown` would be commonest before anything had been measured, and the measurement found it at zero, which is how a defect in the classifier was caught. Read the answer’s own denominators for today’s mix; these say what KIND of mix to expect. A catalogue listing does NOT make a subject an API service. Agents sell priced endpoints too (this platform sells four), so a listing says it sells over HTTP and nothing about which kind of seller. `api-service` is therefore in the vocabulary and is currently UNREACHABLE: separating it would need evidence that a subject does NOT do agent work, and that is an absence, since 86% of these addresses pay nobody on a rail we read and paying from a second wallet looks identical to buying nothing. | |
| filters | No | What was applied, read back, including what a floor excluded. | |
| warnings | No | Anything the server wants a caller to know about THIS answer before acting on it. Empty is the normal case and is not a guarantee. |