Skip to content

feat(symbolConverter): add hip4 recurring outcome support#132

Merged
nktkas merged 5 commits into
nktkas:mainfrom
vtx100:hip4-symbol-converter
Jun 7, 2026
Merged

feat(symbolConverter): add hip4 recurring outcome support#132
nktkas merged 5 commits into
nktkas:mainfrom
vtx100:hip4-symbol-converter

Conversation

@vtx100

@vtx100 vtx100 commented May 7, 2026

Copy link
Copy Markdown
Contributor

Description of the Desired Feature
This PR introduces support for both priceBinary and priceBucket recurring outcomes inside the symbolConverter. It adds full support for generating slugs (identical to the ones used for web URLs) and mapping them to their corresponding assetIds, in accordance with the Hyperliquid documentation for Asset IDs and Contract Specifications.

Motivation and Use Case
Provide a standardized and human friendly way of retrieving assetIds (and eventually other information) about the new HIP4 outcome markets using the hyperliquid URL slug format.

Proposed Solution
I introduced the main orchestrator: _processAllRecurringAssets (which can be easily isolated or toggled via a flag if required). This orchestrator delegates to specific processors depending on how the market data is structured:

  • _processBinaryOutcomeAssets: Handles binary markets where data is provided directly inside the outcomes field of outcomeMeta.
  • _processRecurringBucketOutcomeAssets: Handles multi-price bucket markets. Because bucket responses are standardized, this processor iterates through the questions field and maps the namedOutcomes array to the corresponding entries inside the outcomes array. This makes it straightforward to generate all possible slugs.

Additional Information
Testing limitations: There currently isn't an easy way to write static tests for this feature because the slugs dynamically change based on the day/month. Additionally, the testnet does not provide fixed, long-term markets to test against, so validation requires separate handling.

Scope of the implementation: Support is currently limited to the officially documented recurring outcome markets (so what mainnet does). It does not handle non-standardized testnet cases (for example, the market "What will Hypurr eat the most of in May 2026?", where the name field contains the actual question rather than "Recurring"). These non-standard cases will require separate handling.

Extra: There doesn't seem to be a way to retrieve the getSzDecimals value for a given token, however this seems to be 5 for all markets (which would make sense, considering the nature of the markets), however i've decied not to hardcode this as it doesn't seem to be specified anywhere.

Below is attached a screenshot of the slug->asssetId mapping for currently avaialble mainnet markets:
image

@nktkas

nktkas commented Jun 7, 2026

Copy link
Copy Markdown
Owner

Thanks for kicking this off! I pushed a few changes on top before merging:

  • Reworked slug generation into a single pass over all outcomes
  • Added support for all non-recurring outcome markets (e.g. NBA, World Cup, CPI)
  • Set szDecimals to 5 for outcome markets
  • Added tests

@nktkas nktkas merged commit d634739 into nktkas:main Jun 7, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants