Skip to main content

Discovery and comparison

Outcome. You can enumerate open listings across every Registry you trust, narrow them with that Registry's own filter vocabulary, inspect any listing as JSON, and understand exactly how candidates are compared when you later run market buy.

Prerequisites​

  • The market CLI, verified locally (Start here).
  • At least one Registry URL in [registry] urls, plus a read token under [registry.auth] if that Registry gates reads.

Environment​

market listing commands are read-only: they call each configured Registry's GET /listings and print JSON. No wallet, chain, or storefront is involved.

Query every configured Registry​

market listing list
market listing show <listing_id>

list queries every URL in [registry] urls in parallel and deduplicates the merged results; show returns the first configured Registry that knows the ID. Output is raw JSON in both cases.

Filter with the Registry's vocabulary​

market listing list --gpu-model H200
market listing list --limit 5

Filter vocabulary is per Registry: each operator publishes a filter-spec.yaml that defines which fields (for example gpu_model, region) are validated and queryable, and exposes it at GET /filter-spec. A curated Registry can shrink the vocabulary; a long-tail one can drop constraints entirely. The generic form is market listing list --filter name=value (repeatable). Evidence: the reference filter-spec and the registry-discovery specification.

The VM plugin also maps common constraints onto market buy directly: --gpu-count-min, --region, --vcpu-min, --ram-gb-min, --disk-gb-min, and --token-contract (only consider listings whose accepted escrow uses that ERC-20).

Expected output​

An empty Registry returns []. A populated one returns one JSON object per listing in the Registry's domain vocabulary — publisher attribution, offer_resource, advertised terms, and accepted settlement choices. Annotated examples: Machine-readable records.

Comparison happens under buyer policy​

Discovery only produces candidates. When market buy runs, one buyer aggregation policy owns iteration and comparison — sequential cheapest-first, parallel best-price with an optional timeout, a race for fastest agreement, and other shapes — and returns the winning candidate for your explicit approval. Bound fan-out with max_matches_to_try. The full policy catalog is synchronized in Configuration; the concept view is Agent policy and buyer aggregation.

Troubleshoot​

  • HTTP 401 from a Registry — its reads are gated; the [registry.auth] key must match the configured URL exactly (scheme, host, port, no trailing slash).
  • A filter flag is rejected — that Registry's filter-spec does not define the field. Fetch GET /filter-spec from the Registry to see its vocabulary.
  • Duplicates across Registries — expected before merge; the CLI deduplicates the union it prints.

Next steps​

Source and revision​

The Registry filter vocabulary and discovery behavior cited above are inspected at the exact SCM revision recorded in Source and revisions. This guide does not infer live inventory from that source evidence.