Discovery and Registries

Discovery tells an application which markets and solvers may be available. It does not reserve inventory, bind a price, or implement settlement. Applications may combine curated registries, pinned solver cards, and their own eligibility or ranking policy.

Solver Cards

A solver card is one JSON document per solver and Arkade network. It advertises the markets the solver serves and, when needed, how to request live terms. This example card is valid against the card schema, and its signature verifies:

{
  "version": 0,
  "name": "example-solver",
  "discovery_pubkey": "6575acc9db64e5a5525025bd743684cdd1a1c5edce213c6f41bf5d87babf4e50",
  "transports": {
    "nostr": { "relays": ["wss://relay.example.com"] }
  },
  "markets": [
    {
      "base_asset": { "id": "arkade:bitcoin/slip44:0", "name": "Bitcoin", "ticker": "BTC", "decimals": 8 },
      "quote_asset": { "id": "arkade:bitcoin/asset:f121ac9b7656797cc68d1e8fecacfbaa2069ec1461edf0bf2f3c37404cb9791a0000", "name": "Tether USD", "ticker": "USDT", "decimals": 2 },
      "price_feed": "https://api.example.com/simple/price?ids=bitcoin&vs_currencies=usd",
      "price_feed_schema": { "type": "json", "price_path": "/bitcoin/usd" },
      "price_decimals": 6,
      "fee_bps": 30,
      "min_base_amount": "330",
      "max_base_amount": "10000000",
      "min_quote_amount": "1",
      "max_quote_amount": "10000000"
    },
    {
      "base_asset": { "id": "arkade:bitcoin/slip44:0", "name": "Bitcoin", "ticker": "BTC", "decimals": 8 },
      "quote_asset": { "id": "bolt11:bitcoin/slip44:0", "name": "Bitcoin", "ticker": "BTC", "decimals": 8 },
      "fee_bps": 30,
      "min_base_amount": "500",
      "max_base_amount": "50000",
      "min_quote_amount": "500",
      "max_quote_amount": "50000"
    }
  ],
  "sig": "e54a06c854860d3823a7f18143bf30bfa783c068a7affc8867b65ed8cd0de98a096cd5e900a24c05f395dd11e12fd087420d2b732538662019b7c32cc2b5b46d"
}

The two markets are the two shapes. The first settles both sides through Arkade and its sides carry different assets, so it names a price feed and needs no rendezvous. The second puts its quote side on Lightning through the id bolt11:bitcoin/slip44:0. Both of its sides are BTC, so it names no feed: fee_bps is the whole spread. A corridor market makes the signed discovery_pubkey, transports, and sig mandatory — without them a client has no identity to seal a request to and no relay to send it on.

Field	Role
`version`	Card format version: `0` for the routes these docs cover
`name`	Solver name, unique within one registry and network. In a registry, it matches the card’s file name
`discovery_pubkey`	The solver’s BIP-340 x-only key. It signs the card, and clients address RFQ requests to it
`transports`	`{ "nostr": { "relays": [...] } }`: 1 to 8 relays the solver listens on
`sig`	A BIP-340 Schnorr signature by `discovery_pubkey` over the sha256 of the canonical card: `sig` removed, keys sorted, no whitespace
`markets[]`	The markets the solver serves. Each lists its two sides, a fee, and size bounds. A pointer card omits it, and must then carry `discovery_pubkey`, `transports`, and `sig`
`base_asset`, `quote_asset`	`id`, `name`, `ticker`, and `decimals` for each side. The `id` is a CAIP-19 id, and its namespace names the corridor. Clients group and price by `id` only: `name` and `ticker` are unverified labels
`price_feed`, `price_feed_schema`, `price_decimals`	Where the client reads the spot price. Required when the two sides carry different assets, absent when they carry the same asset
`fee_bps`	The solver’s spread, in basis points
`fee_flat`	Optional. The part of the price that does not scale with size, in quote-asset atomic units
`solver_fee`	Optional. The fee per direction, keyed by the side the user deposits. It supersedes `fee_flat`
`charges_delivered_carrier`	Optional. Whether the solver charges for the dust carrier it delivers with an Arkade asset
`min_base_amount`, `max_base_amount`, `min_quote_amount`, `max_quote_amount`	Size bounds for each side, as decimal strings of atomic units. A bound applies to the amount the solver pays out on that side. A maximum of `"0"` disables that side
`pair`, `base_corridor`, `quote_corridor`	Legacy v0 market fields, accepted only so already-signed cards stay valid during a compatibility window. Current markets omit them

The registry enforces these rules on every card:

A card with a corridor market must carry discovery_pubkey, transports, and sig, and the registry verifies sig. A card whose markets all settle through Arkade can omit them.
The two sides of a market must have different ids. When exactly one side settles through Arkade, that side must be the base side.
Each id names its network, and BTC’s SLIP-44 code depends on it: arkade:bitcoin/slip44:0 on mainnet, and slip44:1 on every test network, such as arkade:mutinynet/slip44:1. A card filed under one network must name only that network.
A market whose two sides carry the same asset must omit the feed fields.

For a market whose endpoints both use arkade, the card advises the pricing formula: which spot feed to read and what spread a fill charges. It remains advisory: it guarantees neither inventory nor that a fill executes.

Registries

A registry is a Git repository of solver cards plus validation and publishing automation. Solvers submit cards through pull requests. The registry validates them and generates one market index per network. Each network’s index carries version, network, generated_at (Unix seconds, set by the publishing job), the source commit, and a flat markets list in which each entry names its solver. Its solvers list holds every card that has a discovery_pubkey. The reference registry publishes https://arkade-os.github.io/solver-registry/<network>.json for bitcoin, signet, mutinynet, and regtest, and the swap client follows it by default. Currently (2026-10-31) the mainnet index lists no solvers, so an application on mainnet discovers no markets from it without a pinned card. The discovery client treats an index older than 7 days as stale. It warns, holds back the markets that index snapshotted, and still accepts a listed solver’s fresh card over its relays. After 28 days a stale index vouches for no solver.

Cards over Nostr

A solver also publishes its signed card on its relays as an addressable Nostr event of kind 38859, with a d tag naming the network. For each solver an index lists, the discovery client fetches that card and uses its markets in place of the index snapshot. It accepts the card only when:

name and discovery_pubkey match the listing;
the card carries markets (a pointer carries no markets);
sig verifies and the card passes the schema;
the event was published within 7200 seconds of now, in either direction.

A pointer card in a registry lists only the solver’s identity and relays, so its markets always come from the card on Nostr. A solver can then change its terms without a registry pull request. Registry review is a listing gate, not a settlement trust anchor. A merged card can become stale, and an index cannot move funds.

Application Curation

No registry is mandatory. An application can:

follow one or more public or private registries;
pin a solver card directly;
filter by route, size, issuer policy, jurisdiction, or reputation;
re-rank solvers using fill history or other product-owned data;
remove solvers without changing the settlement protocol.

When combining registries, isolate failures, validate every index, remove byte-identical duplicates, and keep source attribution. A solver omitted from one registry remains reachable through another registry or a pinned card.

Ranking and Best Execution

A generated index sorts each pair’s markets by fee_bps, then by solver name. That order is a static proxy, not a ranking: a market with a flat fee can cost more at small sizes than a market with a higher fee_bps. Price freshness, routing capacity, inventory, reliability, and application policy also affect execution quality.

Trust Model

Treat cards, indexes, advertisements, and price feeds as advisory. For corridor RFQ, verify the signed rendezvous and every signed quote. On every route, derive the settlement contract locally before value moves.

Understand Intents

Build with Intents

Earn Fees

Reference

Solver Cards

Registries

Cards over Nostr

Application Curation

Ranking and Best Execution

Trust Model

Sources

​Solver Cards

​Registries

​Cards over Nostr

​Application Curation

​Ranking and Best Execution

​Trust Model

​Sources

Solver Cards

Registries

Cards over Nostr

Application Curation

Ranking and Best Execution

Trust Model

Sources