Skip to Content
Symmio Trading-SDK — the SDK surface for builders on HyperEVM
CoreAddresses

Addresses

@symmio/trading-core ships a per-chain registry of every deployment address, endpoint URL, and configured service. It lives in the core package at:

packages/trading-core/src/core/chains/registry.ts

The registry is the single source of truth for chain-specific values. Every action reads it via Config.getChainConfig(chainId) — you never hand-thread addresses through action arguments unless you’re overriding a default.

Runtime access

import { createConfig, SymmioSupportedChainId } from "@symmio/trading-core";
 
const config = createConfig({
  symmioConfig: {
    [SymmioSupportedChainId.HYPER_EVM]: { addresses: { affiliatesAddress: "0xYourRegisteredAffiliate…" } },
  },
  getClient: () => publicClient,
});
 
const chain = config.getChainConfig(999);
 
chain.addresses.symmioAddress;
chain.addresses.instantLayerAddress;
chain.addresses.accountLayerAddress;
chain.addresses.affiliatesAddress;
chain.addresses.collateralAddress;
chain.addresses.collateralDecimals;

Throws UNSUPPORTED_CHAIN when the chain id isn’t in the registry. See Config.

What’s in the registry

Every entry is a SymmioChainConfig — the fully-resolved settings for one chain:

chainIdnumber

Numeric chain id (e.g. 999 for HyperEVM).

addressesSymmioContractAddresses

On-chain contract addresses (detailed below).

subgraphsSymmioSubgraphUrls

GraphQL endpoints — analytics and events.

solversRecord<SolverId, SymmioSolverConfig>

Solver / hedger REST API, TP/SL handler, optional per-solver price service, and the required per-solver notifications config, keyed by solver id ("enigma" / "rasa"). HyperEVM carries the enigma solver; Base carries rasa. Resolve one with config.getSolver({ chainId, solverId }).

defaultSolverIdSolverId

The solver an action or hook resolves when solverId is omitted — enigma on HyperEVM, rasa on Base. Read it at runtime with config.getDefaultSolverId(chainId?).

priceServiceSymmioPriceServiceConfig

Price provider — the Enigma price service on HyperEVM (type: "enigma"), or Binance USD-M Futures on Base (type: "binance"). Both expose REST + WebSocket.

muonSymmioMuonConfig

Muon oracle gateway URLs.

listingSymmioListingConfigoptional

The Pools listing backend — a single url, and that url is the host root: no version segment and no trailing slash, because the generated client’s own paths already begin with /v2. Chain-level rather than per-solver, since several solvers on one chain could share one deployment. Present only on HyperEVM today. See Pools listing service.

inventorySymmioInventoryConfigoptional

The inventory service — the custody backend behind the Pools, and a different vendor from both the solver and the listing backend. A single url, again the host root: the generated client’s own paths already begin with /api/v1, so appending /api here would request /api/api/v1/… and 404. Chain-level, and unlike listing there is no solver capability to declare — a chain either carries the block or it does not, which is why resolveInventoryService takes a bare chainId. Missing, it throws INVENTORY_NOT_CONFIGURED. Present only on HyperEVM today.

The addresses field — the section people usually want:

symmioAddressAddress

SYMMIO diamond contract.

instantLayerAddressAddress

InstantLayer (delegated instant actions).

accountLayerAddressAddress

AccountLayer (SubAccount / VA management).

affiliatesAddressAddress

Your frontend’s affiliate identity (fee attribution). Required per chain via createConfig’s symmioConfig[chainId].addresses.affiliatesAddress — the field must be present (createConfig throws when it is missing). The zero address is accepted as a no-affiliate test placeholder; ` register your affiliate  to earn a share of the trading fees.

collateralAddressAddress

Collateral token (e.g. USDC).

collateralDecimalsnumber

Decimals of the collateral token.

Each entry in solvers is a SymmioSolverConfig — the solver’s own endpoints, including its notifications config:

namestring

Human-readable solver name.

addressAddress

Solver’s on-chain address (used as partyB in sendQuoteWithAffiliateAndData).

urlstring

Solver / hedger REST API base URL.

tpslSymmioTpSlConfigoptional

TP/SL (conditional-order handler) config — the solver supports conditional orders only when set.

priceServiceSymmioPriceServiceConfigoptional

Price source for this solver’s markets. Falls back to the chain’s priceService when omitted.

notificationsSymmioNotificationsConfig

Per-solver notifications config — WebSocket url + a protocol discriminant ("enigma" / "rasa"). The enigma variant adds channel and an optional searchUrl (the notification service that backs searchNotifications); the rasa variant has neither — its history search runs through the solver’s own position-state endpoint, also via searchNotifications. Required on every solver: notifications are inherently solver-specific, so there is no chain-level default to inherit.

Everything else (subgraph, Muon gateways, the chain-level price service) lives on the sibling SymmioChainConfig fields above.

Current chains

Two chains ship in the registry — each runs a different solver kind and product. See Solvers & Chains for how the two axes fit together.

HyperEVM (999) — enigma / lowcap

  • symmioAddress — 0x57331038c21982116EE9b0906E4a5c5cB52dcE2e
  • instantLayerAddress — 0x72DBF07457b2712b160F67A85D338F860c1CA620
  • accountLayerAddress — 0x46493c376758Da47823D7E3Ae5d417eA6546eEB3
  • affiliatesAddress — 0xBcB033C9154401fA000a1Ae60843f79f45741b7c (built-in default; override it per chain via the required symmioConfig[chainId].addresses.affiliatesAddress — set your registered affiliate  to earn a share of the trading fees)
  • collateralAddress — 0xb88339CB7199b77E23DB6E890353E22632Ba630f (USDC, 6 decimals)
  • solvers.enigma.address — 0x76bc5889c0cfcC20960b0D81F541595d81a95122, defaultSolverId: "enigma"
  • solvers.enigma.tpsl.cohWalletAddress — 0xf2afbb3f13Ca72bfb69749f3bC5EbD6528b1fc31
  • solvers.enigma.notifications.protocol — "enigma" (carries a searchUrl — the notification service)
  • priceService.type — "enigma"
  • listing.url — https://listing85.enigma.bz (the Pools listing backend; host root, no /v2)
  • inventory.url — https://inventory85.enigma.bz (the custody backend behind the Pools; host root, no /api)

Base (8453) — rasa / majors

  • symmioAddress — 0x91Cf2D8Ed503EC52768999aA6D8DBeA6e52dbe43
  • instantLayerAddress — 0x0825435285ac0E5c02c7a7c443F631f3e07fE375
  • accountLayerAddress — 0x56caf00c6C5cB5478570Bb23807B9d1D697863DC
  • affiliatesAddress — 0x45Eecd7B4f442388ACD90467E423A5CAAC3a9C3f (built-in default; override with your registered affiliate)
  • collateralAddress — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC on Base, 6 decimals)
  • solvers.rasa.address — 0x81631953E0C093e72935C1CAA4C7D519B2A0E407, defaultSolverId: "rasa"
  • solvers.rasa.notifications.protocol — "rasa" (no searchUrl; history search runs through the solver’s own position-state endpoint via searchNotifications)
  • priceService.type — "binance" (Binance USD-M Futures, fapi.binance.com)

Base is staging-configured. The rasa solver.url points at a staging host (stage-archon.rasa.capital), and the subgraph endpoints are HyperEVM placeholders (they return HyperEVM data, not Base data) until Base’s own subgraphs ship — override them via symmioConfig[8453].subgraphs when you have real endpoints. Base has no tpsl block: the COH wallet is not deployed yet, so conditional orders (TP/SL) are unsupported on Base. Muon gateways are real (Muon is deployment-agnostic). Swap the staging solver URL for production when it’s published.

Each entry also carries URLs for the solver, price service, notifications, subgraphs, and Muon gateways.

Per-chain overrides

Override any field at runtime via createConfig({ symmioConfig }). Deep-merged onto the built-in registry — you can override just the subgraph URL or just one address, keeping the rest.

const config = createConfig({
  getClient: () => publicClient,
  symmioConfig: {
    999: {
      addresses: { affiliatesAddress: "0xYourRegisteredAffiliate…" },
      subgraphs: {
        analytics: "https://staging.example/subgraphs/analytics",
      },
      // Notifications are per-solver — override under `solvers[solverId].notifications`.
      solvers: {
        enigma: { notifications: { searchUrl: "https://staging.example/notification" } },
      },
    },
  },
});

Useful for staging deployments and new chains that ship before an SDK release.

Adding a chain

  1. Add its id to packages/trading-core/src/core/chains/supported-chains.ts — sourced from viem/chains, never a numeric literal.
  2. Add its entry to CHAIN_CONFIGS in packages/trading-core/src/core/chains/registry.ts — every field of SymmioChainConfig is required.
  3. Colocate tests for getChainConfig if you introduce novel behavior.

Open a PR. New chains follow the existing entries’ conventions.

  • Config — how getChainConfig / symmioConfig plug in.
  • ABI fragments — pair addresses with typed ABIs for viem-direct calls.
  • Shared Types — ChainIdParameter mixin on every action.
Last updated on
ABI fragmentsOverview