Crystal

All asset balances, markets, and trading functionality are accessible through a single central contract featuring swap endpoints across the orderbook, AMM, and launchpad.

Functions

feeRecipient

function feeRecipient() external view returns (address)

Recipient address of protocol fees.

Return Values

Name	Type	Description
address	address	Address that receives the fee

---

feeCommission

function feeCommission() external view returns (uint8)

Referrer’s commission rate

Return Values

Name	Type	Description
feeCommission	uint8	Global referrer commission rate in percent

---

userIdToAddress

function userIdToAddress(uint256) external view returns (address)

Retrieves the wallet address associated with a specific user ID.

Parameters

Name	Type	Description
userId	uint256	The userId

Return Values

Name	Type	Description
user	address	The address associated with the given userId

---

addressToUserId

function addressToUserId(address) external view returns (uint256)

Retrieves the numeric user ID that corresponds to a given wallet address.

Parameters

Name	Type	Description
user	address	The address for which to retrieve the userId

Return Values

Name	Type	Description
userId	uint256	The numeric user ID corresponding to user

---

claimableRewards

function claimableRewards(address, address) external view returns (uint256)

Returns accrued rewards for (token, user); claim via claimFees

Parameters

Name	Type	Description
token	address	ERC-20 token (WETH for native) in which rewards accrue.
user	address	Account whose claimable balance is queried.

Return Values

Name	Type	Description
amount	uint256	Accrued but unclaimed rewards for (token, user)

---

latestUserId

function latestUserId() external view returns (uint256)

Returns the most recently issued userId.

Return Values

Name	Type	Description
latestUserId	uint256	Numeric result

---

gov

function gov() external view returns (address)

Returns the current governance address.

Return Values

Name	Type	Description
gov	address	Current governance/admin address.

---

feeClaimDuration

function feeClaimDuration() external view returns (uint256)

Seconds to wait before an expired-fees queue can be executed.

Return Values

Name	Type	Description
duration	uint256	Delay (in seconds) required between queuing and executing expired fee claims.

---

getMarketByTokens

function getMarketByTokens(address, address) external view returns (address)

Looks up market address given an asset pair. May return a placeholder address for launchpad tokens before graduation; not routable until migrated.

Parameters

Name	Type	Description
assetIn	address	Input asset (WETH for native)
assetOut	address	Output asset (WETH for native)

Return Values

Name	Type	Description
market	address	Market contract for the pair, placeholder for launchpad pairs pre-graduation, or zero if none.

---

marketToMarketId

function marketToMarketId(address) external view returns (uint256)

Returns the numeric marketId for a market address.

Parameters

Name	Type	Description
market	address	Address parameter

Return Values

Name	Type	Description
marketId	uint256	Numeric result

---

marketIdToMarket

function marketIdToMarket(uint256) external view returns (address)

Returns the market address for a numeric marketId.

Parameters

Name	Type	Description
marketId	uint256	Numeric market ID.

Return Values

Name	Type	Description
market	address	Market contract address.

---

isCanonicalDeployer

function isCanonicalDeployer(address) external view returns (bool)

Flag: address is allowed to deploy canonical markets.

Parameters

Name	Type	Description
deployer	address	Address to check

Return Values

Name	Type	Description
allowed	bool	True if address qualifies

---

allMarkets

function allMarkets(uint256) external view returns (address)

Paging accessor over all market addresses.

Parameters

Name	Type	Description
index	uint256	Zero-based index into the markets array.

Return Values

Name	Type	Description
market	address	Market address at index.

---

parameters

function parameters() external view returns (address, address, uint256, uint256, uint256, uint256, uint256)

Returns global Parameters tuple (quote/base, market id/type, scale, tick, max price).

Return Values

Name	Type	Description
quoteAsset	address	Quote token for the market under construction.
baseAsset	address	Base token for the market under construction.
marketId	uint256	Numeric ID assigned for deterministic deployment.
marketType	uint256	Pricing mode (e.g., linear/decimal/tiered).
scaleFactor	uint256	Decimal scaling for price math.
tickSize	uint256	Minimum price increment.
maxPrice	uint256	Upper bound used to seed tick bitmaps.

---

launchpadParams

function launchpadParams() external view returns (uint112, uint256, uint256, uint256, uint256, uint256, uint256)

Returns global LaunchpadParams tuple (initial supply, fees/splits, graduated params).

Return Values

Name	Type	Description
launchpadInitialNativeSupply	uint112	Initial virtual native liquidity.
launchpadFee	uint256	Fee factor (scaled base 100_000) on launchpad trades.
launchpadCreatorFeeSplit	uint256	Creator share of launchpad fees (percent)
graduatedMinSize	uint256	Min order size for the graduated market.
graduatedTakerFee	uint256	Taker fee after graduation
graduatedMakerRebate	uint256	Maker rebate after graduation
graduatedCreatorFeeSplit	uint256	Creator fee split post-graduation (percent)

---

launchpadTokenToMarket

function launchpadTokenToMarket(address) external view returns (uint112, uint112, uint256, address, address, uint88)

Returns the LaunchpadMarket tuple bound to a token (virtual reserves, k, creator/market addresses, timestamp).

Parameters

Name	Type	Description
token	address	Launchpad token to query.

Return Values

Name	Type	Description
virtualNativeReserve	uint112	Simulated native-side reserve.
virtualTokenReserve	uint112	Simulated token-side reserve.
k	uint256	Constant product used for bonding curve.
creator	address	Token creator entitled to fee split.
market	address	Spot market address to migrate into on graduation.
createTimestamp	uint88	Launch time used for inactivity windows.

---

allTokens

function allTokens(uint256) external view returns (address)

Paging accessor over all launchpad-created tokens.

Parameters

Name	Type	Description
index	uint256	Zero-based index into launchpad-created tokens.

Return Values

Name	Type	Description
token	address	oken address at index

---

weth

function weth() external view returns (address)

Returns the canonical WETH address used by the router.

Return Values

Name	Type	Description
weth	address	Canonical WETH contract used for wrapping/unwrapping.

---

eth

function eth() external view returns (address)

Returns the placeholder/native ETH address constant.

Return Values

Name	Type	Description
eth	address	Sentinel constant representing native ETH (0xEeee…EEeE).

---

allMarketsLength

function allMarketsLength() external view returns (uint256)

Returns the number of deployed markets.

Return Values

Name	Type	Description
length	uint256	Total number of deployed markets stored in the registry.

---

getMarket

function getMarket(address market) external view returns (MarketInfo)

Retrieves stored market data (book top, fees, reserves, etc.).

Parameters

Name	Type	Description
market	address	Market address

Return Values

Name	Type	Description
info	MarketInfo	Struct containing live market data (quote/base, price bounds, fees, reserves, AMM state).

---

getDepositedBalance

function getDepositedBalance(address user, address asset) external view returns (uint256, uint256, uint256)

Returns balances held by protocol for user in asset.

Parameters

Name	Type	Description
user	address	Account whose balances are queried.
asset	address	Token address (use WETH sentinel for ETH).

Return Values

Name	Type	Description
total	uint256	Total tokens held in protocol custody.
available	uint256	Portion free for withdrawal or new orders.
locked	uint256	Portion reserved for active orders or liquidity.

---

getAllOrdersByCloid

function getAllOrdersByCloid(address user, uint256 range) external view returns (uint256[], Order[])

Returns batched packed ids and decoded Order[] for a user’s CLOID bucket (windowed by range).

Parameters

Name	Type	Description
user	address	Wallet to inspect
range	uint256	Maximum CLOID window to scan (up to 1023).

Return Values

Name	Type	Description
cloids	uint256[]	Array of client order IDs found.
userOrders	Order[]	Decoded order data matching each CLOID.

---

getOrderByCloid

function getOrderByCloid(uint256 userId, uint256 cloid) external view returns (Order)

Returns a single Order stored under composite CLOID for that user.

Parameters

Name	Type	Description
userId	uint256	User identifier
cloid	uint256	Client order ID

Return Values

Name	Type	Description
order	Order	Full order struct stored under that composite key.

---

getOrder

function getOrder(address market, uint256 price, uint256 id) external view returns (Order)

Returns a specific Order by (market, price level, native id).

Parameters

Name	Type	Description
market	address	Market address
price	uint256	Order price
id	uint256	Order identifier

Return Values

Name	Type	Description
order	Order	Order details.

---

getPriceLevel

function getPriceLevel(address market, uint256 price) external view returns (PriceLevel)

Returns PriceLevel aggregate for a specific price.

Parameters

Name	Type	Description
market	address	Market address
price	uint256	Order price

Return Values

Name	Type	Description
priceLevel	PriceLevel	Aggregate liquidity and internal pointers for that level.

---

getPriceLevels

function getPriceLevels(address market, bool isAscending, uint256 startPrice, uint256 distance, uint256 interval, uint256 max) external returns (bytes)

Returns encoded order-book data for initialized price levels starting from a given price and direction.

Parameters

Name	Type	Description
market	address	Market address
isAscending	bool	If true, search for price levels in the space above startPrice, otherwise search below
startPrice	uint256	Start price, inclusive
distance	uint256	How many price increments to check
interval	uint256	Step between prices
max	uint256	Maximum number of entries

Return Values

Name	Type	Description
priceLevels	bytes	Byte string containing 32 byte chunks, with the first 16 bytes the price and last 16 bytes the sum of all order sizes at the price level

---

getPriceLevelsFromMid

function getPriceLevelsFromMid(address market, uint256 distance, uint256 interval, uint256 max) external returns (uint256, uint256, bytes, bytes)

Returns the best bid and ask along with encoded order-book data for price levels around the mid-price.

Parameters

Name	Type	Description
market	address	Target market
distance	uint256	How many price increments to check each way
interval	uint256	Step size between ticks.
max	uint256	Maximum number of entries

Return Values

Name	Type	Description
highestBid	uint256	The price of the highest buy order
lowestAsk	uint256	The price of the lowest sell order
bids	bytes	Byte string representing all buy orders within distance of the bid-ask spread
asks	bytes	Byte string representing all sell orders within distance of the bid-ask spread

---

getPrice

function getPrice(address market) external returns (uint256, uint256, uint256)

Returns price, highestBid, lowestAsk given a market address. Delegated to market via delegatecall; non-view.

Parameters

Name	Type	Description
market	address	Market address

Return Values

Name	Type	Description
price	uint256	Mid Price
highestBid	uint256	Best bid price
lowestAsk	uint256	Best ask price

---

getQuote

function getQuote(address market, bool isBuy, bool isExactInput, bool isCompleteFill, uint256 size, uint256 worstPrice) external returns (uint256, uint256)

Simulates a trade to calculate the expected input and output amounts given trade direction, size, and worst acceptable price.

Parameters

Name	Type	Description
market	address	Market address
isBuy	bool	True for buy orders, false for sell
isExactInput	bool	True for exact input mode, false for exact output
isCompleteFill	bool	Whether to require complete fill
size	uint256	Order size
worstPrice	uint256	Worst acceptable execution price

Return Values

Name	Type	Description
amountIn	uint256	Input tokens required
amountOut	uint256	Output tokens required

---

deploy

function deploy(bool isCanonical, address quoteAsset, address baseAsset, uint256 marketType, uint256 scaleFactor, uint256 tickSize, uint256 maxPrice, uint256 minSize, uint24 takerFee, uint24 makerRebate) external returns (address)

Deploys a new order-book market with the provided parameters; returns the market address.

Parameters

Name	Type	Description
isCanonical	bool	Determines if market is canonical
quoteAsset	address	Quote token address
baseAsset	address	Base token address
marketType	uint256	Market type identifier
scaleFactor	uint256	Price scaling factor
tickSize	uint256	Minimum price increment
maxPrice	uint256	Maximum allowed price
minSize	uint256	Minimum order size
takerFee	uint24	Taker fee in basis points
makerRebate	uint24	Maker rebate in basis points

Return Values

Name	Type	Description
market	address	Newly deployed market contract.

---

registerUser

function registerUser(address caller) external returns (uint256)

Registers a wallet to enable limit-order placement; this is automatically handled when routing through the main contract.

Parameters

Name	Type	Description
caller	address	Address of the user

Return Values

Name	Type	Description
userId	uint256	Newly assigned numeric user identifier.

---

deposit

function deposit(address token, uint256 amount) external payable returns (uint256)

Deposits ERC-20 or native (if msg.value) into protocol custody; returns credited amount (post-wrap/scale).

Parameters

Name	Type	Description
token	address	Token contract address
amount	uint256	Quantity to deposit

Return Values

Name	Type	Description
userId	uint256	Depositing user’s ID (auto-created if new)

---

withdraw

function withdraw(address to, address token, uint256 amount) external

Withdraws user custody balance to to

Parameters

Name	Type	Description
to	address	Recipient address
token	address	Token contract address
amount	uint256	Amount of tokens

---

routerDeposit

function routerDeposit(address token, uint256 amount) external payable

Router-privileged path to deposit on behalf of a user (supports msg.value).

Parameters

Name	Type	Description
token	address	Token contract address
amount	uint256	Deposit quantity

---

routerWithdraw

function routerWithdraw(address to, address token, uint256 amount) external

Router-privileged withdrawal on behalf of a user.

Parameters

Name	Type	Description
to	address	Recipient address
token	address	Token contract address
amount	uint256	Amount of tokens

---

claimFees

function claimFees(address to, address[] tokens) external returns (uint256[])

Claims accumulated maker rebates or referral fees owed to the caller.

Parameters

Name	Type	Description
to	address	Recipient address
tokens	address[]	Array of token addresses

Return Values

Name	Type	Description
amounts	uint256[]	Claimed amount per token.

---

queueClaimExpiredFees

function queueClaimExpiredFees(address user, address[] tokens) external

Schedules recovery of expired, unclaimed fees for user.

Parameters

Name	Type	Description
user	address	Address of the user
tokens	address[]	Array of token addresses

---

executeClaimExpiredFees

function executeClaimExpiredFees(address user) external returns (uint256[])

Executes the queued expired-fee claim and returns recovered amounts.

Parameters

Name	Type	Description
user	address	Address of the user

Return Values

Name	Type	Description
amounts	uint256[]	Amounts successfully recovered per token.

---

changeGov

function changeGov(address newGov) external

Updates configuration parameters.

Parameters

Name	Type	Description
newGov	address	Address of new governance controller

---

changeFeeRecipient

function changeFeeRecipient(address newFeeRecipient) external

Updates configuration parameters.

Parameters

Name	Type	Description
newFeeRecipient	address	New wallet to receive protocol fees.

---

changeFeeClaimDuration

function changeFeeClaimDuration(uint256 newFeeClaimDuration) external

Claims accumulated fees or rewards.

Parameters

Name	Type	Description
newFeeClaimDuration	uint256	New delay (seconds) between queue + execute expired-fee claim.

---

changeRefFeeStructure

function changeRefFeeStructure(uint8 newFeeCommission, uint8 newFeeRebate) external

Updates configuration parameters.

Parameters

Name	Type	Description
newFeeCommission	uint8	Proposed new referrer commission rate (%).
newFeeRebate	uint8	Proposed maker rebate (%).

---

changeMarketParams

function changeMarketParams(address market, uint256 newMinSize, uint24 newTakerFee, uint24 newMakerRebate, bool isAMMEnabled, bool isCanonical) external

Updates configuration parameters.

Parameters

Name	Type	Description
market	address	Target market to update.
newMinSize	uint256	Updated minimum order size.
newTakerFee	uint24	Updated taker fee (scaled bps).
newMakerRebate	uint24	Updated maker rebate (scaled bps).
isAMMEnabled	bool	Toggle AMM hybrid mode.
isCanonical	bool	Toggle canonical-routing flag.

---

changeMarketCreatorFee

function changeMarketCreatorFee(address market, address newCreator, uint256 newCreatorFee) external

Updates configuration parameters.

Parameters

Name	Type	Description
market	address	Market address
newCreator	address	Updated creator address.
newCreatorFee	uint256	Creator fee split

---

changeLaunchpadParams

function changeLaunchpadParams(LaunchpadParams newLaunchpadParams) external

Updates configuration parameters.

Parameters

Name	Type	Description
newLaunchpadParams	LaunchpadParams	Struct containing updated launchpad global settings.

---

addCanonicalDeployer

function addCanonicalDeployer(address deployer) external

Grant canonical-deployer status.

Parameters

Name	Type	Description
deployer	address	Address parameter

---

removeCanonicalDeployer

function removeCanonicalDeployer(address deployer) external

Revoke canonical-deployer status.

Parameters

Name	Type	Description
deployer	address	Address parameter

---

approveForwarder

function approveForwarder(address forwarder) external

Approves an address for privileged actions.

Parameters

Name	Type	Description
forwarder	address	Contract or EOA allowed to submit orders on caller’s behalf.

---

removeForwarder

function removeForwarder(address forwarder) external

Removes an address from authorization.

Parameters

Name	Type	Description
forwarder	address	Address parameter

---

clearCloidSlots

function clearCloidSlots(uint256 userId, uint256[] ids) external

Clears stored data.

Parameters

Name	Type	Description
userId	uint256	User whose order slots to clear.
ids	uint256[]	CLOID identifiers being reset.

---

getReserves

function getReserves(address market) external returns (uint112, uint112)

Returns current reserve balances.

Parameters

Name	Type	Description
market	address	Market address

Return Values

Name	Type	Description
reserveQuote	uint112	Current quote-token reserve.
reserveBase	uint112	Current base-token reserve.

---

addLiquidity

function addLiquidity(address market, address to, uint256 amountQuoteDesired, uint256 amountBaseDesired, uint256 amountQuoteMin, uint256 amountBaseMin) external payable returns (uint256)

Adds liquidity to a market.

Parameters

Name	Type	Description
market	address	Market address to supply liquidity to.
to	address	Recipient address of LP position.
amountQuoteDesired	uint256	Intended quote deposit.
amountBaseDesired	uint256	Intended base deposit.
amountQuoteMin	uint256	Minimum acceptable quote.
amountBaseMin	uint256	Minimum acceptable base.

Return Values

Name	Type	Description
liquidity	uint256	Minted liquidity amount.

---

removeLiquidity

function removeLiquidity(address market, address to, uint256 liquidity, uint256 amountQuoteMin, uint256 amountBaseMin) external returns (uint256, uint256)

Removes liquidity from a market.

Parameters

Name	Type	Description
market	address	Market address
to	address	Recipient address
liquidity	uint256	LP tokens to burn.
amountQuoteMin	uint256	Minimum quote token amount
amountBaseMin	uint256	Minimum base token amount

Return Values

Name	Type	Description
amountQuote	uint256	Quote tokens returned.
amountBase	uint256	Base tokens returned.

---

removeLiquidityETH

function removeLiquidityETH(address market, address to, uint256 liquidity, uint256 amountQuoteMin, uint256 amountBaseMin) external returns (uint256 amountQuote, uint256 amountBase)

Removes liquidity from a market.

Parameters

Name	Type	Description
market	address	Market address
to	address	Recipient address
liquidity	uint256	Liquidity amount
amountQuoteMin	uint256	Minimum quote token amount
amountBaseMin	uint256	Minimum base token amount

Return Values

Name	Type	Description
amountQuote	uint256	Quote token amount
amountBase	uint256	Base token amount

---

marketOrder

function marketOrder(address market, bool isBuy, bool isExactInput, uint256 options, uint256 orderType, uint256 size, uint256 worstPrice, address referrer, address user) external returns (uint256, uint256, uint256)

Executes a market order.

Parameters

Name	Type	Description
market	address	Market address
isBuy	bool	True = buy False = sell.
isExactInput	bool	Indicates whether size is input or output.
options	uint256	Bit-flags for ETH handling and mode
orderType	uint256	Internal order execution type.
size	uint256	Trade amount.
worstPrice	uint256	Maximum slippage or price limit.
referrer	address	Optional referral address.
user	address	Account placing the order

Return Values

Name	Type	Description
amountIn	uint256	Tokens spent
amountOut	uint256	Tokens received
id	uint256	Residual order ID if partially filled

---

limitOrder

function limitOrder(address market, bool isBuy, uint256 options, uint256 price, uint256 size, address user) external returns (uint256)

Places a limit order.

Parameters

Name	Type	Description
market	address	Market address
isBuy	bool	True = buy False = sell.
options	uint256	Execution flags.
price	uint256	Limit price.
size	uint256	Order size
user	address	Address of the user

Return Values

Name	Type	Description
id	uint256	Created order ID.

---

cancelOrder

function cancelOrder(address market, uint256 options, uint256 price, uint256 id, address user) external returns (uint256)

Cancels an existing order.

Parameters

Name	Type	Description
market	address	Market address
options	uint256	Execution flags
price	uint256	Price level
id	uint256	Order ID
user	address	Address of the user

Return Values

Name	Type	Description
size	uint256	Amount canceled and released.

---

replaceOrder

function replaceOrder(address market, uint256 options, uint256 price, uint256 id, uint256 newPrice, uint256 size, address referrer, address user) external returns (uint256)

Places a limit order.

Parameters

Name	Type	Description
market	address	Market address
options	uint256	Flags for mode
price	uint256	Old price level
id	uint256	Order ID
newPrice	uint256	New price level
size	uint256	New Order size
referrer	address	Referrer address for fee sharing
user	address	Address of the user

Return Values

Name	Type	Description
id	uint256	New or current order ID.

---

batchOrders

function batchOrders(address market, Action[] actions, uint256 options, uint256 deadline, address referrer, address user) external payable

Executes multiple limit or market order in a single transaction; failed actions simply return 0.

Parameters

Name	Type	Description
market	address	Market address
actions	Action[]	Array of actions to execute
options	uint256	Bitfield of execution options
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing
user	address	Address of the user

---

getAmountsOut

function getAmountsOut(uint256 amountIn, address[] path) external returns (uint256[])

Calculates token amounts for routing. (eth sentinel auto-mapped to WETH at each hop; reverts on unresolved market or placeholder)

Parameters

Name	Type	Description
amountIn	uint256	Input token amount
path	address[]	Token swap path

Return Values

Name	Type	Description
amounts	uint256[]	Expect Output per hop, final element is total output

---

getAmountsIn

function getAmountsIn(uint256 amountOut, address[] path) external returns (uint256[])

Calculates token amounts for routing. (eth sentinel auto-mapped to WETH at each hop; reverts on unresolved market or placeholder)

Parameters

Name	Type	Description
amountOut	uint256	Output token amount
path	address[]	Token swap path

Return Values

Name	Type	Description
amounts	uint256[]	Required input per hop, final element is total input

---

swapExactETHForTokens

function swapExactETHForTokens(uint256 amountOutMin, address[] path, address to, uint256 deadline, address referrer) external payable returns (uint256[])

Swaps tokens via routing.

Parameters

Name	Type	Description
amountOutMin	uint256	Minimum acceptable output amount
path	address[]	Token swap path
to	address	Recipient address
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

Return Values

Name	Type	Description
amounts	uint256[]	Numeric result

---

swapExactTokensForETH

function swapExactTokensForETH(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline, address referrer) external returns (uint256[])

Swaps tokens via routing.

Parameters

Name	Type	Description
amountIn	uint256	Input token amount
amountOutMin	uint256	Minimum acceptable output amount
path	address[]	Token swap path
to	address	Recipient address
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

Return Values

Name	Type	Description
	uint256[]	Numeric result

---

swapExactTokensForTokens

function swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline, address referrer) external returns (uint256[])

Swaps tokens via routing.

Parameters

Name	Type	Description
amountIn	uint256	Input token amount
amountOutMin	uint256	Minimum acceptable output amount
path	address[]	Token swap path
to	address	Recipient address
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

Return Values

Name	Type	Description
	uint256[]	Numeric result

---

swapETHForExactTokens

function swapETHForExactTokens(uint256 amountOut, address[] path, address to, uint256 deadline, address referrer) external payable returns (uint256[])

Swaps tokens via routing.

Parameters

Name	Type	Description
amountOut	uint256	Output token amount
path	address[]	Token swap path
to	address	Recipient address
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

Return Values

Name	Type	Description
	uint256[]	Numeric result

---

swapTokensForExactETH

function swapTokensForExactETH(uint256 amountOut, uint256 amountInMax, address[] path, address to, uint256 deadline, address referrer) external returns (uint256[])

Swaps tokens via routing.

Parameters

Name	Type	Description
amountOut	uint256	Output token amount
amountInMax	uint256	Maximum input amount willing to pay
path	address[]	Token swap path
to	address	Recipient address
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

Return Values

Name	Type	Description
	uint256[]	Numeric result

---

swapTokensForExactTokens

function swapTokensForExactTokens(uint256 amountOut, uint256 amountInMax, address[] path, address to, uint256 deadline, address referrer) external returns (uint256[])

Swaps tokens via routing.

Parameters

Name	Type	Description
amountOut	uint256	Output token amount
amountInMax	uint256	Maximum input amount willing to pay
path	address[]	Token swap path
to	address	Recipient address
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

Return Values

Name	Type	Description
	uint256[]	Numeric result

---

swap

function swap(bool exactInput, address tokenIn, address tokenOut, uint256 orderType, uint256 size, uint256 worstPrice, uint256 deadline, address referrer) external payable returns (uint256, uint256, uint256)

Swaps tokens via routing.

Parameters

Name	Type	Description
exactInput	bool	Boolean flag
tokenIn	address	Input token address
tokenOut	address	Output token address
orderType	uint256	Type of order
size	uint256	Order size
worstPrice	uint256	Worst acceptable execution price
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

Return Values

Name	Type	Description
userId	uint256	Numeric result
balanceOrOut	uint256	Numeric result
id	uint256	Numeric result

---

placeLimitOrder

function placeLimitOrder(address tokenIn, address tokenOut, uint256 price, uint256 size, uint256 deadline) external payable returns (uint256)

Places a limit order.

Parameters

Name	Type	Description
tokenIn	address	Input token address
tokenOut	address	Output token address
price	uint256	Order price
size	uint256	Order size
deadline	uint256	Expiry

Return Values

Name	Type	Description
id	uint256	Created order identifier

---

cancelLimitOrder

function cancelLimitOrder(address tokenIn, address tokenOut, uint256 price, uint256 id, uint256 deadline) external returns (uint256)

Cancels an existing order.

Parameters

Name	Type	Description
tokenIn	address	Input token address
tokenOut	address	Output token address
price	uint256	Order price
id	uint256	Order identifier
deadline	uint256	Expiry

Return Values

Name	Type	Description
size	uint256	Order size

---

replaceOrder

function replaceOrder(bool isPostOnly, bool isDecrease, address tokenIn, address tokenOut, uint256 price, uint256 id, uint256 newPrice, uint256 newSize, uint256 deadline, address referrer) external payable returns (uint256)

Places a limit order.

Parameters

Name	Type	Description
isPostOnly	bool	Prevent immediate fills if true
isDecrease	bool	True if reducing size
tokenIn	address	Input token address
tokenOut	address	Output token address
price	uint256	Order price
id	uint256	Order ID
newPrice	uint256	New order price
newSize	uint256	New order size
deadline	uint256	Expiry
referrer	address	Referrer address

Return Values

Name	Type	Description
id	uint256	New/Current Order ID

---

multiBatchOrders

function multiBatchOrders(Batch[] batches, uint256 deadline, address referrer) external payable

Executes cross-market batches atomically. (ETH handling: “Wraps ETH to WETH for in-call usage; refunds residual WETH as ETH at end.)

Parameters

Name	Type	Description
batches	Batch[]	Array of batches to execute
deadline	uint256	Transaction deadline timestamp
referrer	address	Referrer address for fee sharing

---

createToken

function createToken(string name, string symbol, string metadataCID, string description, string social1, string social2, string social3, string social4) external payable returns (address token)

Creates a new entity. Also deploys launchpad market in ‘placeholder’ routing state; on optional attached ETH, triggers initial buy.

Parameters

Name	Type	Description
name	string	Token name
symbol	string	Token symbol
metadataCID	string	IPFS metadata CID
description	string	Text description
social1	string	Social media link
social2	string	Social media link
social3	string	Social media link
social4	string	Social media link

Return Values

Name	Type	Description
token	address	Deployed token address

---

buy

function buy(bool isExactInput, address token, uint256 amountIn, uint256 amountOut) external payable returns (uint256, uint256, bool)

Buys tokens from the market.

Parameters

Name	Type	Description
isExactInput	bool	True for exact input mode, false for exact output
token	address	Token contract address
amountIn	uint256	Input token amount
amountOut	uint256	Output token amount

Return Values

Name	Type	Description
inputAmount	uint256	ETH spent
outputAmount	uint256	Tokens received
graduated	bool	True = market auto-graduated

---

sell

function sell(bool isExactInput, address token, uint256 amountIn, uint256 amountOut) external returns (uint256, uint256)

Sells tokens to the market.

Parameters

Name	Type	Description
isExactInput	bool	True for exact input mode, false for exact output
token	address	Launchpad token
amountIn	uint256	Tokens sold
amountOut	uint256	Expected WETH/ETH output

Return Values

Name	Type	Description
inputAmount	uint256	Tokens sold
outputAmount	uint256	ETH received

---

getVirtualReserves

function getVirtualReserves(address token) external view returns (uint256, uint256)

For launchpad tokens only; Returns current reserve balances, zeroes indicate its already graduated.

Parameters

Name	Type	Description
token	address	Launchpad token address

Return Values

Name	Type	Description
virtualNativeReserve	uint256	Virtual native-side liquidity.
virtualTokenReserve	uint256	Virtual token-side liquidity.

---

Fallback

The fallback function is gas-optimized and intended for use by market makers and other high frequency automated trading strategies. Calldata is in 32 byte chunks, with the first chunk being a flag to use internal balance (first byte being the action (0 = cancel, 1 = limit buy, 2 = limit sell, 3 = market buy, 4 = market sell), trailing 10 bytes of the first 16 bytes being the price level to place/cancel limit orders, or the worst acceptable price for market orders, and last 16 bytes being the order size for market/limit orders or the id of the order to cancel. Each 32 byte chunk represents an action, and msg.sender is used as all address parameters for each action.

Example: 0x000000000000001c4bc5cb6b2c2f42a57bd35c5fb0ea6d80c9c17368100000000000002600000000000000000000000000000000000000000000000010000000000000250000000000000000000000000000000000000000000000001000000000000020000000000000000000000000000000000000000000000000100000000000001f000000000000000000000000000000000000000000000000100000000000001800000000000000000000000000000000000000000000000010000000000000170000000000000000000000000000000000000000000000001000000000000014000000000000000000000000000000000000000000000000100000000000001300000000000000000000000000000000000000000000000010000000000000120000000000000000000000000000000000000000000000001000000000000011000000000000000000000000000000000000000000000000100000000000000e000000000000000000000000000000000000000000000000100000000000000d00000000000000000000000000000000000000000000000010000000000000020000000000000000000000000000000000000000000000001000000000000001000000000000000000000000000000000000000000000000400000000000000100000000000000019fca0000000000000000000000989680400000000000000d0000000000000001997e0000000000000000000017d78400400000000000001100000000000000018efe0000000000000000000005f5e100400000000000001300000000000000018ce40000000000000000000001c9c380400000000000001700000000000000018ba20000000000000000000001c9c380400000000000001f000000000000000147500000000000000000000005f5e100400000000000002500000000000000013b010000000000000000000017d78400500000000000000200000000000000019fcb00000000000000000000000024b2500000000000000e0000000000000001a600000000000000000000000005a65450000000000000120000000000000001b05800000000000000000000000160ee50000000000000140000000000000001b269000000000000000000000000696050000000000000180000000000000001b3a7000000000000000000000000691350000000000000200000000000000001f6880000000000000000000000012fa3500000000000002600000000000000020316000000000000000000000004a0f3

---

Events

MarketCreated

event MarketCreated(indexed bool isCanonical, indexed address quoteAsset, indexed address baseAsset, address market, ICrystal.TokenMetadata quoteInfo, ICrystal.TokenMetadata baseInfo, ICrystal.MarketDetails marketInfo);

Deployed new market with its assets and setup details.

Parameters

Name	Type	Description
isCanonical	indexed bool	Determines if market is canonical.
quoteAsset	indexed address	Quote token address
baseAsset	indexed address	Base token address
market	address	Market address
quoteInfo	ICrystal.TokenMetadata	Parameter value
baseInfo	ICrystal.TokenMetadata	Parameter value
marketInfo	ICrystal.MarketDetails	Parameter value

---

MarketParamsChanged

event MarketParamsChanged(indexed address market, uint256 minSize, uint24 takerFee, uint24 makerRebate, bool isAMMEnabled);

A market’s key settings (like fees or minimum size) were updated.

Parameters

Name	Type	Description
market	indexed address	Market address
minSize	uint256	Minimum order size
takerFee	uint24	Taker fee in basis points
makerRebate	uint24	Maker rebate in basis points
isAMMEnabled	bool	True = AMM backstop is enabled

---

GovChanged

event GovChanged(address prev, address gov);

Protocol governance address changed.

Parameters

Name	Type	Description
prev	address	Prev gov address
gov	address	New gov address

---

UserRegistered

event UserRegistered(indexed bool isMargin, indexed address user, indexed uint256 userId);

Emitted when a new user is registered.

Parameters

Name	Type	Description
isMargin	indexed bool	Account Type, right now its false for spot
user	indexed address	REgistered wallet address
userId	indexed uint256	User identifier

---

Deposit

event Deposit(indexed address user, indexed uint256 userId, indexed address token, uint256 amount);

Emitted when user deposits a token into protocol custody.

Parameters

Name	Type	Description
user	indexed address	Depositor's address
userId	indexed uint256	Depositor's user ID
token	indexed address	Token deposited
amount	uint256	Amount of tokens

---

Withdraw

event Withdraw(indexed address user, indexed uint256 userId, indexed address token, uint256 amount);

Emitted when user deposits a token from protocol custody.

Parameters

Name	Type	Description
user	indexed address	Recipient wallet
userId	indexed uint256	Recipient's user ID
token	indexed address	Token contract address
amount	uint256	Amount sent out

---

RewardsClaimed

event RewardsClaimed(indexed address user, address[] tokens, uint256[] amounts);

Emitted when rewards or fees are claimed.

Parameters

Name	Type	Description
user	indexed address	Address of the user
tokens	address[]	Tokens claimed
amounts	uint256[]	Amounts per token

---

Trade

event Trade(indexed address market, indexed address user, bool isBuy, uint256 amountIn, uint256 amountOut, uint256 startPrice, uint256 endPrice);

Emitted when a trade is executed.

Parameters

Name	Type	Description
market	indexed address	Market address
user	indexed address	Trader wallet
isBuy	bool	True if buy, false if sell
amountIn	uint256	Spent amount
amountOut	uint256	Received amount
startPrice	uint256	Price when order is placed
endPrice	uint256	Price when order is filled

---

OrdersUpdated

event OrdersUpdated(indexed address market, indexed address user, bytes orderData);

Represents a limit order’s key data — price, size, order type, user ID, and partial-fill progress indicators.

Parameters

Name	Type	Description
market	indexed address	Market address
user	indexed address	Order owner address
orderData	bytes	Compact batch of placed/changed/canceled orders.

---

Fill

event Fill(indexed address market, indexed address user, uint256 fillInfo, uint256 fillAmount);

Emitted when an order is filled.

Parameters

Name	Type	Description
market	indexed address	Market address
user	indexed address	Order owner address
fillInfo	uint256	Bit 255 is set to 1 if the aggressing fill is a sell order, 0 if buy. Bits 168-248 is the price, 112-168 is the order id, and 0-112 is the remaining size
fillAmount	uint256	Size of fill

---

TokenCreated

event TokenCreated(indexed address token, indexed address creator, string name, string symbol, string metadataCID, string description, string social1, string social2, string social3, string social4);

Emitted when a new entity is created.

Parameters

Name	Type	Description
token	indexed address	Token contract address
creator	indexed address	Token creator address
name	string	Token name
symbol	string	Token symbol
metadataCID	string	IPFS metadata CID
description	string	Description text
social1	string	Social media link
social2	string	Social media link
social3	string	Social media link
social4	string	Social media link

---

Migrated

event Migrated(indexed address token);

Emitted when migration occurs (e.g., to market)

Parameters

Name	Type	Description
token	indexed address	Token contract address

---

LaunchpadTrade

event LaunchpadTrade(indexed address token, indexed address user, bool isBuy, uint256 amountIn, uint256 amountOut, uint256 virtualNativeReserve, uint256 virtualTokenReserve);

Launchpad swap executed with updated virtual reserves.

Parameters

Name	Type	Description
token	indexed address	Token contract address
user	indexed address	Address of the user
isBuy	bool	True for buy orders, false for sell
amountIn	uint256	Input token amount
amountOut	uint256	Output token amount
virtualNativeReserve	uint256	Post-swap native token reserve
virtualTokenReserve	uint256	Post-swap launchpad token reserve

---

Mint

event Mint(indexed address market, indexed address sender, uint amountQuote, uint amountBase);

Emitted when liquidity is added to a market pair with actual amounts.

Parameters

Name	Type	Description
market	indexed address	Market address
sender	indexed address	Address parameter
amountQuote	uint	Quote token amount
amountBase	uint	Base token amount

---

Burn

event Burn(indexed address market, indexed address sender, uint amountQuote, uint amountBase, indexed address to);

Liquidity removed from a market pair with actual amounts and recipient.

Parameters

Name	Type	Description
market	indexed address	Market address
sender	indexed address	Address parameter
amountQuote	uint	Quote token amount
amountBase	uint	Base token amount
to	indexed address	Recipient address

---

Sync

event Sync(indexed address market, uint112 reserve0, uint112 reserve1);

Emitted when reserves are synchronized.

Parameters

Name	Type	Description
market	indexed address	Market address
reserve0	uint112	Numeric value
reserve1	uint112	Numeric value

---

Structs

InternalOrder

struct InternalOrder {
    uint256 size;
    uint256 orderType;
    uint256 userId;
    uint256 fillBefore;
    uint256 fillAfter;
}

Compact internal storage format for an order, tracking size, type, user, and partial-fill progress.

Parameters

Name	Type	Description
size	uint256	Order size
orderType	uint256	Type of order
userId	uint256	User identifier
fillBefore	uint256	Fill before timestamp
fillAfter	uint256	Fill after timestamp

---

Order

struct Order {
    bool isBuy;
    address market;
    uint256 price;
    uint256 size;
    uint256 orderType;
    uint256 userId;
    uint256 fillBefore;
    uint256 fillAfter;
}

Order showing side, market, price, size, user, and how much of it is filled.

Parameters

Name	Type	Description
isBuy	bool	True for buy orders, false for sell
market	address	Market address
price	uint256	Order price
size	uint256	Order size
orderType	uint256	Type of order
userId	uint256	User identifier
fillBefore	uint256	Fill before timestamp
fillAfter	uint256	Fill after timestamp

---

PriceLevel

struct PriceLevel {
    uint256 size;
    uint256 latestNativeId;
    uint256 latest;
    uint256 fillNext;
}

Aggregates all orders at a single price level, tracking total size and sequencing identifiers for fill order.

Parameters

Name	Type	Description
size	uint256	Order size
latestNativeId	uint256	Numeric value
latest	uint256	Numeric value
fillNext	uint256	Numeric value

---

Market

struct Market {
    uint80 highestBid;
    uint80 lowestAsk;
    uint40 minSize;
    uint24 takerFee;
    uint24 makerRebate;
    bool isAMMEnabled;
    uint112 reserveQuote;
    uint112 reserveBase;
    address quoteAsset;
    address baseAsset;
    uint256 marketId;
    uint256 marketType;
    uint256 scaleFactor;
    uint256 tickSize;
    uint256 maxPrice;
    address creator;
    uint88 createTimestamp;
    uint8 creatorFeeSplit;
}

Canonical on-chain market config and state: quotes/base assets, fees, size/tick/price bounds, AMM toggle, reserves, creator info, ids, and creation time.

Parameters

Name	Type	Description
highestBid	uint80	Best bid
lowestAsk	uint80	Best ask
minSize	uint40	Minimum order size
takerFee	uint24	Taker fee in basis points
makerRebate	uint24	Maker rebate in basis points
isAMMEnabled	bool	Whether AMM is enabled
reserveQuote	uint112	Quote reserve (LP)
reserveBase	uint112	Base reserve (LP)
quoteAsset	address	Quote token address
baseAsset	address	Base token address
marketId	uint256	Market identifier
marketType	uint256	Market type identifier
scaleFactor	uint256	Decimal scale for price math.
tickSize	uint256	Minimum price increment
maxPrice	uint256	Upper price bound
creator	address	Address parameter
createTimestamp	uint88	Numeric value
creatorFeeSplit	uint8	Numeric value

---

MarketInfo

struct MarketInfo {
    address quoteAsset;
    address baseAsset;
    uint256 marketType;
    uint256 highestBid;
    uint256 lowestAsk;
    uint256 scaleFactor;
    uint256 tickSize;
    uint256 maxPrice;
    uint256 minSize;
    uint256 takerFee;
    uint256 makerRebate;
    uint256 reserveQuote;
    uint256 reserveBase;
    bool isAMMEnabled;
}

Market’s key info for UIs, like top prices, fees, reserves, and settings.

Parameters

Name	Type	Description
quoteAsset	address	Quote token address
baseAsset	address	Base token address
marketType	uint256	Market type identifier
highestBid	uint256	Best bid (widened)
lowestAsk	uint256	Best ask (widened)
scaleFactor	uint256	Price scaling factor
tickSize	uint256	Price tick size
maxPrice	uint256	Max price boundary
minSize	uint256	Minimum order size
takerFee	uint256	Taker fee (scaled)
makerRebate	uint256	Maker rebate (scaled)
reserveQuote	uint256	Quote LP reserve
reserveBase	uint256	Base LP reserve
isAMMEnabled	bool	Whether AMM is enabled

---

TokenMetadata

struct TokenMetadata {
    address token;
    uint256 decimals;
    string ticker;
    string name;
}

Token metadata including address, decimals, ticker, and name.

Parameters

Name	Type	Description
token	address	Token address
decimals	uint256	Decimal precision
ticker	string	String value
name	string	Name string

---

MarketDetails

struct MarketDetails {
    uint256 marketId;
    uint256 marketType;
    uint256 scaleFactor;
    uint256 tickSize;
    uint256 maxPrice;
    uint256 minSize;
    uint256 takerFee;
    uint256 makerRebate;
}

Set parameters for a market: ids, scale/tick/max price, min size, and fee schedule.

Parameters

Name	Type	Description
marketId	uint256	Market identifier
marketType	uint256	Market type identifier
scaleFactor	uint256	Price scaling factor
tickSize	uint256	Minimum tick
maxPrice	uint256	Upper price bound
minSize	uint256	Minimum order size
takerFee	uint256	Taker fee (scaled)
makerRebate	uint256	Maker rebate (scaled)

---

Action

struct Action {
    bool isRequireSuccess;
    uint256 action;
    uint256 param1;
    uint256 param2;
    uint256 param3;
}

Single instruction inside a batch (e.g., place/cancel/replace); isRequireSuccess gates revert behavior, action op-code with up to three numeric params.

Parameters

Name	Type	Description
isRequireSuccess	bool	If true, revert batch on sub-action failure
action	uint256	Opcode (e.g., place/cancel/replace/market)
param1	uint256	First numeric parameter
param2	uint256	Second numeric parameter.
param3	uint256	Third numeric parameter.

---

Batch

struct Batch {
    address market;
    Action[] actions;
    uint256 options;
}

Collection of Action to execute atomically on one market, with an options bitfield for execution flags.

Parameters

Name	Type	Description
market	address	Target market for all actions in the batch.
actions	Action[]	Ordered list of sub-operations.
options	uint256	Bitfield flags

---

Parameters

struct Parameters {
    address quoteAsset;
    address baseAsset;
    uint256 marketId;
    uint256 marketType;
    uint256 scaleFactor;
    uint256 tickSize;
    uint256 maxPrice;
}

Holds market-level configuration such as quote/base asset addresses, market ID, scaling factor, tick size, and maximum price

Parameters

Name	Type	Description
quoteAsset	address	Quote token address
baseAsset	address	Base token address
marketId	uint256	Market identifier
marketType	uint256	Market type identifier
scaleFactor	uint256	Price scaling factor
tickSize	uint256	Minimum price increment
maxPrice	uint256	Upper bound for ticks

---

LaunchpadMarket

struct LaunchpadMarket {
    uint112 virtualNativeReserve;
    uint112 virtualTokenReserve;
    uint256 k;
    address creator;
    address market;
    uint88 createTimestamp;
}

State of a launchpad token market.

Parameters

Name	Type	Description
virtualNativeReserve	uint112	Bonding-curve native reserve
virtualTokenReserve	uint112	Bonding-curve token reserve
k	uint256	Constant product
creator	address	Creator address (for fee split)
market	address	Market address after graduation
createTimestamp	uint88	Creation time

---

LaunchpadParams

struct LaunchpadParams {
    uint112 launchpadInitialNativeSupply;
    uint256 launchpadFee;
    uint256 launchpadCreatorFeeSplit;
    uint256 graduatedMinSize;
    uint256 graduatedTakerFee;
    uint256 graduatedMakerRebate;
    uint256 graduatedCreatorFeeSplit;
}

Launchpad settings: initial native supply, fees/splits, and “graduated” market params after launch.

Parameters

Name	Type	Description
launchpadInitialNativeSupply	uint112	Initial virtual native liquidity.
launchpadFee	uint256	Fee factor (base 100_000)
launchpadCreatorFeeSplit	uint256	Creator share of fees
graduatedMinSize	uint256	Post-graduation min size
graduatedTakerFee	uint256	Post-graduation taker fee (scaled)
graduatedMakerRebate	uint256	Post-graduation maker rebate
graduatedCreatorFeeSplit	uint256	Creator fee split after graduation

---

PendingExpiredFeeClaim

struct PendingExpiredFeeClaim {
    uint256 deadline;
    address[] tokens;
    uint256[] amounts;
}

Queued claim of expired fees for a user: deadline plus token list and amounts.

Parameters

Name	Type	Description
deadline	uint256	Earliest time this claim can be executed.
tokens	address[]	Tokens included in the claim.
amounts	uint256[]	Snapshotted amounts at queue time.

---