SYMMIO Trading-SDK
The frontend boundary between UI and SYMMIO.
An SDK-first workspace: the libraries that make SYMMIO buildable, and the apps that prove they are.
Website · Documentation · SDK console · Contributing
SYMMIO is a hybrid clearing house for permissionless derivatives. The product behind it is built by many vendors with different architectures: contracts, solvers, subgraphs, oracles, price feeds, and notification services. Building a UI directly against that raw surface means learning all of it.
This repo exists so you don't have to. It ships an SDK that hides the complexity behind an API that is simple, correct, and reliable — plus the apps we build on top of it, which are the proof that the SDK is good enough to build real products with.
Looking for how to use the SDK? Everything — install, config, and every action, hook, and type — lives on the documentation site.
Packages
Two SDK layers, and a strict rule about what goes where: trading-core never imports a framework, so a framework layer can be added without rewriting it.
| Package | Version | Description |
|---|
@symmio/trading-core | | Framework-agnostic SDK. Contract reads/writes via viem, solver REST, subgraph GraphQL, Muon attestations, price and notification streams, and the calculations that turn raw protocol data into typed results. |
@symmio/trading-react | | React adapter. A hook and a provider for everything in core, with caching and invalidation wired through TanStack Query and wagmi. |
@symmio/utils | | Framework-agnostic helpers: amount formatting, address shortening, a Decimal.js bridge. |
@symmio/session-key | | Local EVM session keys — generate, persist through an injected storage interface, and sign without a wallet prompt. |
Not part of the SDK surface — SDK consumers never need these:
Chain support: Arbitrum One (42161) and Base (8453) ship today. The plumbing is chain-keyed throughout, so adding another chain is a registry entry rather than a refactor.
Development
For working on this repository, see the development and release guide, including when to use staging releases, versioning, npm authentication, publication, and production releases.
If you want to build a product on top of the SDK, read the documentation — and especially the Build a Perps DEX guide — to learn the flow of building a trading product: how to deposit, open a trade, set TP/SL, withdraw, and more.
The three integration facts humans and AI agents most often get wrong — affiliate defaults, the available-balance model, and the two decimal scales — are called out at the top of that guide: Three facts integrators get wrong most often.
Requires Node ≥ 20 and pnpm (the version in packageManager; corepack enable picks it up). This repo is pnpm-only — npm install or yarn here will produce a broken tree.
pnpm install
pnpm dev # every app, via Turborepo
All commands run from the repo root and fan out through Turborepo:
| Command | What it does |
|---|
pnpm dev | Run every app's dev server (and the packages' watch builds). |
pnpm build | Build everything in dependency order. |
pnpm lint | ESLint, zero-warnings. |
pnpm check-types | tsc --noEmit across the workspace. |
pnpm test | Unit tests (Vitest). Integration tests stay gated behind SYMM_RUN_INTEGRATION and a funded key. |
pnpm format | Prettier. |
pnpm verify-packages | Verify the published shape of the packages — see below. |
Scope any of them to one package with pnpm --filter @symmio/trading-core test, or run it from that package's directory.
The docs typecheck waits for its own build in Turbo. Both next build and next typegen write to apps/docs/.next, so running them concurrently can delete route types while they are being generated. Use pnpm exec turbo run check-types --filter=@symmio/docs to preserve this ordering; do not run the direct docs typecheck alongside a docs build.
Lefthook runs Prettier, ESLint, and type-checks pre-commit, and commitlint on the message — commits follow Conventional Commits.
Verifying published output
pnpm lint and pnpm check-types only ever exercise workspace symlinks under bundler resolution, so they cannot catch a broken subpath export, an unresolvable .d.ts, or a file missing from the tarball. pnpm verify-packages packs each package, lints the tarball with publint and @arethetypeswrong/cli, then installs it into a consumer outside the workspace and type-checks it under strict nodenext before importing it at runtime. CI runs this on every PR.
Releasing
Versioning is Changesets-driven. Add one with pnpm changeset in any PR that changes a published package; merging to main opens or refreshes the "Version Packages" PR. Merging that PR starts publication, gated by approval of the GitHub release environment and valid npm publishing credentials.
For changes that need testing before production, follow the staging release procedure. It covers prerelease versions, the staging dist-tag, and npm's separate staged-upload approval flow.
PR package previews
Opening, reopening, or pushing commits to a PR runs the CI checks, then publishes the PR head's six public packages through pkg.pr.new. Its bot updates one PR comment with pnpm installation commands. Each preview uses its own package.json version with a -preview-<sha> suffix: for example, 3.1.0 becomes 3.1.0-preview-a832a55, while 1.0.0 becomes 1.0.0-preview-a832a55. Internal dependencies resolve to matching previews. Version changes happen only in the CI checkout; no changeset or npm release is needed to try them.
Copy the install command for the package you need from the PR comment. See Preview Releases for installation, updating a preview, and switching back to npm releases.
One-time setup: a repository admin must install the pkg.pr.new GitHub App for SYMM-IO/SYMM-Frontier. Preview publishing needs no npm token or release-environment approval. The CLI is a pinned root dev dependency, executed from the lockfile in CI. Fork PRs may need a maintainer to approve the Actions run under the repository's existing policy.
Contributing
Read AGENTS.md first — it is the contract for this repo, for humans and AI coding agents alike, and it covers the hard rules (pnpm only, TypeScript only, core stays framework-agnostic), the file and naming conventions, and the Design Proposal Gate: non-trivial changes to trading-core or trading-react get a written design proposal and explicit approval before any implementation code is written. Several packages add their own AGENTS.md that applies on top of the root one.
Keep increments small and reviewable — one SDK slice per PR.
License
MIT © SYMMIO
