Hyperliquid Deployers

Hyperliquid markets are listed by deployers — independent HIP-4 publishers, each identified by a short namespace (ap, aq, …). Two deployers can list the same real-world market independently. When they do, sufwan-local-test sees two Hyperliquid listings of one question.

This page covers how those listings surface, how to tell them apart, and the one place where treating them as interchangeable will give a user depth they cannot trade against.

What a deployer isCopy Anchor Link

On Hyperliquid, the venue does not publish markets — deployers do. Each deployer runs its own contracts and its own orderbook. Two deployers listing "Arsenal vs Chelsea" are publishing two distinct, non-fungible instruments: separate tokens, separate books, separate settlement.

That is the critical property. Everywhere else in sufwan-local-test, two listings of the same question live on different venues, and a user picks one. Here they live on the same venue, and the distinction is the deployer namespace.

How duplicate listings surfaceCopy Anchor Link

sufwan-local-test clusters the two Hyperliquid listings together through a non-Hyperliquid anchor. If the same market is also on Polymarket, both Hyperliquid listings match Polymarket, and transitively land in one cluster:

Matched cluster
  ├── venueEvent (polymarket)                    ← anchor
  ├── venueEvent (hyperliquid, deployer "ap")    ← member
  └── venueEvent (hyperliquid, deployer "aq")    ← member

So GET /venue-events returns one row, and matchedVenueEvents[] carries two entries with venue: "hyperliquid".

Detecting itCopy Anchor Link

Count Hyperliquid entries rather than assuming one:

const hlMembers = event.matchedVenueEvents.filter((m) => m.venue === "hyperliquid");
if (hlMembers.length > 1) {
  // Same question, multiple deployers. Their books are not interchangeable.
}

The same applies one level down: a market's matchedVenueMarkets[] can carry more than one venue: "hyperliquid" sibling.

When they do not clusterCopy Anchor Link

Cross-deployer clustering needs the non-Hyperliquid anchor. Two deployers listing a market that no other venue carries have no middle node, so they stay two separate clusters — two rows from GET /venue-events, two tiles.

This is expected, not a gap. Hyperliquid-only markets are the common case for long-tail listings. If you need to collapse those in your own UI, group on aggKey — with its caveats, chiefly that it is null for a substantial share of rows.

Naming the deployerCopy Anchor Link

deployerVenue is exposed on the orderbook batch response, not on discovery rows. Request the cluster's market ids and read it off matchedMarkets[]:

const { data } = await client.getOrderbooks({ venueMarketIds: ["vm_abc", "vm_def"] });
const deployers = data[0]?.matchedMarkets?.map((m) => m.deployerVenue);

Full shape on Get live orderbooks for multiple markets.

{
  "data": [
    {
      "venueMarketId": "vm_abc",
      "status": "ok",
      "matchedMarkets": [
        { "venue": "polymarket",  "venueMarketId": "vm_abc", "hasOrderbook": true,  "deployerVenue": null },
        { "venue": "hyperliquid", "venueMarketId": "vm_def", "hasOrderbook": true,  "deployerVenue": "ap" },
        { "venue": "hyperliquid", "venueMarketId": "vm_ghi", "hasOrderbook": true,  "deployerVenue": "aq" }
      ],
      "venueOrderbooks": {
        "polymarket":  { "venueMarketId": "vm_abc", "orderbook": { "bids": [], "asks": [] }, "deployerVenue": null },
        "hyperliquid": { "venueMarketId": "vm_def", "orderbook": { "bids": [], "asks": [] }, "deployerVenue": "ap" }
      }
    }
  ]
}

deployerVenue is null for every non-Hyperliquid venue, and null for Hyperliquid listings that carry no deployer namespace.

Reading the right bookCopy Anchor Link

Note the asymmetry in the response above: matchedMarkets[] has three entries, venueOrderbooks has two.

Two fields keep this straight:

Which member gets published is deterministic (lowest venueMarketId), so it does not flip between polls while cluster membership is unchanged — but treat it as an implementation detail and read deployerVenue rather than assuming.

Practical guidanceCopy Anchor Link

• Rendering a venue badge row — de-duplicate by venue. Two Hyperliquid members are still "one venue" from a badge's point of view, and venues[] / venueCount on the event row already reflect that.
• Rendering a price comparison — do not de-duplicate. Each deployer is a separately tradeable price; collapsing them hides a real execution choice from the user.
• Executing — carry the specific venueMarketId through from quote to order. That id, not the venue name, identifies what gets traded.
• Persisting — (venue, externalIdentifier) remains the durable handle, and it already distinguishes deployers. Do not build a key from venue alone for Hyperliquid.

RelatedCopy Anchor Link