@pear-protocol/symmio-client

@pear-protocol/symmio-client

Pear Protocol's standalone SDK for Symmio — account management via MultiAccount, trading, deposits/withdrawals, batch operations, ClearingHouse, and administrative actions.

Package rename: this SDK now publishes as @pear-protocol/symmio-client.

Installation

bun add @pear-protocol/symmio-client viem

viem is a peer dependency and must be installed alongside @pear-protocol/symmio-client.

Quick Start

import { SymmioSDK } from '@pear-protocol/symmio-client';
import { createPublicClient, createWalletClient, http, custom } from 'viem';
import { arbitrum } from 'viem/chains';

// Set up viem clients
const publicClient = createPublicClient({
  chain: arbitrum,
  transport: http(),
});

const walletClient = createWalletClient({
  chain: arbitrum,
  transport: custom(window.ethereum),
});

// Initialize the Symmio client SDK
const sdk = new SymmioSDK({
  chainId: 42161,
  publicClient,
  walletClient,
});

Core Actions

Account Management

// Create an account
const hash = await sdk.account.addAccount('Trading Account');

// Edit account name
await sdk.account.editName(accountAddress, 'New Name');

// Get all accounts for a user
const accounts = await sdk.account.getAll(userAddress);

// Get account count
const count = await sdk.account.getCount(userAddress);

Token Approval

// Approve the MultiAccount contract to spend your USDC
await sdk.approval.approveCollateral(amount);

// Check approval state
import { ApprovalState } from '@pear-protocol/symmio-client';
const state = await sdk.approval.getState(tokenAddr, owner, spender, amount);

Deposits

// Standard deposit
await sdk.deposit.standard({
  account: '0x...',
  amount: 100_000_000n, // 100 USDC (6 decimals)
});

// Deposit and allocate in a single transaction
await sdk.deposit.depositAndAllocate({
  account: '0x...',
  amount: 100_000_000n,
});

Withdrawals

// Withdraw from an account
await sdk.withdraw.withdraw({
  account: '0x...',
  amount: 50_000_000n,
});

Instant Withdrawal (bridge + bot)

For the small-pool instant / 12h withdrawal flow (auth, fee options, bridge, and the orchestrated useSymmInstantWithdraw hook), see INSTANT_WITHDRAWAL.md.

Allocate / Deallocate

// Allocate collateral to trading
await sdk.collateral.allocate(subAccount, { amount: 50_000_000n });

// Deallocate with Muon signature
const deallocSig = await sdk.getDeallocateSig(subAccount);
await sdk.collateral.deallocate(subAccount, {
  amount: 25_000_000n,
  upnlSig: deallocSig,
});

// Internal transfer between accounts
await sdk.collateral.internalTransfer(subAccount, {
  recipient: otherAccount,
  amount: 10_000_000n,
});

Trading

import { PositionType, OrderType, MARKET_ORDER_DEADLINE } from '@pear-protocol/symmio-client';

// Get Muon signature for opening a position
const quoteSig = await sdk.getQuoteSig(subAccount, symbolId);

// Open a position
await sdk.trade.sendQuote(subAccount, {
  partyBsWhiteList: ['0x...'],
  symbolId: 1,
  positionType: PositionType.LONG,
  orderType: OrderType.MARKET,
  price: 50000_000000000000000000n,
  quantity: 1_000000000000000000n,
  cva: ...,
  lf: ...,
  partyAmm: ...,
  partyBmm: ...,
  maxFundingRate: ...,
  deadline: BigInt(Math.floor(Date.now() / 1000)) + MARKET_ORDER_DEADLINE,
  affiliate: '0x...',
  upnlSig: quoteSig,
});

// Batch open multiple positions with one Muon sig
const batchSig = await sdk.getBatchSig(subAccount, [1, 2, 3]);
await sdk.trade.batchSendQuote(subAccount, {
  quotes: [quote1, quote2, quote3],
  upnlSig: batchSig,
});

// Close a position
await sdk.trade.closePosition(subAccount, {
  quoteId: 1n,
  closePrice: price,
  quantityToClose: quantity,
  orderType: OrderType.MARKET,
  deadline: BigInt(Math.floor(Date.now() / 1000)) + MARKET_ORDER_DEADLINE,
});

// Cancel operations
await sdk.trade.cancelQuote(subAccount, quoteId);
await sdk.trade.cancelCloseRequest(subAccount, quoteId);

Delegation

// Delegate access to trading selectors
await sdk.delegation.delegateAccess({
  account: subAccount,
  delegate: delegateAddress,
  selectors: ALL_TRADING_SELECTORS,
});

// Propose to revoke access (starts cooldown)
await sdk.delegation.proposeRevoke({
  account: subAccount,
  delegate: delegateAddress,
  selectors: ALL_TRADING_SELECTORS,
});

// Revoke access (after cooldown)
await sdk.delegation.revokeAccess({
  account: subAccount,
  delegate: delegateAddress,
  selectors: ALL_TRADING_SELECTORS,
});

Terms of Service

// Sign and store terms on-chain
const sig = await sdk.signature.signTerms();
await sdk.signature.storeSignature(sig);

// Check if user has signed
const hasSigned = await sdk.signature.hasSigned(userAddress);

Direct Action Modules

For advanced usage, all action modules are exported individually:

import {
  accountActions,
  depositActions,
  withdrawActions,
  allocateActions,
  tradeActions,
  closeActions,
  cancelActions,
  approvalActions,
  delegationActions,
  signatureActions,
  adminActions,
} from '@pear-protocol/symmio-client';

// Use prepare* functions for framework integration (wagmi, ethers, etc.)
const prepared = tradeActions.prepareSendQuote(
  multiAccount,
  account,
  subAccount,
  params
);
// prepared.config contains { account, to, data, value }

Utilities

import { toWei, fromWei, formatPrice, applySlippage } from '@pear-protocol/symmio-client';

const amount = toWei('100', 6);         // 100000000n
const display = fromWei(100000000n, 6);  // "100"
const slipped = applySlippage(price, 1.0, true); // +1% for longs

Architecture

@pear-protocol/symmio-client
├── client.ts          → SymmioSDK class (main entry point)
├── actions/           → All on-chain transaction builders + executors
│   ├── account.ts     → Account management (MultiAccount)
│   ├── deposit.ts     → Standard deposits
│   ├── withdraw.ts    → Withdrawals
│   ├── allocate.ts    → Allocate, deallocate, internal transfer
│   ├── trade.ts       → Open positions, batch, pair trades
│   ├── close.ts       → Close, batch close, ADL close
│   ├── cancel.ts      → Cancel quotes and close requests
│   ├── approval.ts    → ERC-20 token approvals
│   ├── delegation.ts  → Delegation and access management
│   ├── signature.ts   → Terms of service signing & storage
│   └── admin.ts       → Role admin
├── abis/              → Contract ABIs
├── clients/           → External service clients (Muon)
├── constants/         → Addresses, chains, selectors, defaults
├── types/             → Full TypeScript type system
└── utils/             → Encoding, gas, validation, formatting

Releases

This package uses Changesets for versioning and npm publishing.

# create a release note for your change
bun run changeset

# apply pending version bumps and refresh bun.lock
bun run version-packages

# publish the package to npm
bun run release

The GitHub Actions release workflow expects an NPM_TOKEN repository secret with publish access to @pear-protocol/symmio-client.

License

MIT