When you open a price position you pick a position mode. The mode decides whether the position stands alone, merges with an existing one, and whether it is margined on its own or shares collateral with your other positions through a margin account.

​
Position modes

  • Separate — each open creates an independent position with its own collateral and health. A market limits how many separate position buckets one wallet can hold (between 1 and 5, set per market).
  • Full — same-direction opens merge into a single long or short bucket for your wallet. A merge can change the bucket’s effective entry price and leverage, and it does not consume another position slot.
  • CrossSeparate — like Separate, but the position is held by your margin account and shares collateral with your other cross positions.
  • CrossFull — like Full, but inside your margin account: same-pool, same-direction opens merge into one cross position.
Separate and Full are margined per position. CrossSeparate and CrossFull are margined together at the account level — that is what the rest of this page covers.

​
Margin accounts

A margin account (UserMarginAccount) is a user-owned contract that holds collateral and a set of cross-margined positions, so profit on one position can support another instead of each position being collateralized in isolation.
  • You create one with MarginAccountFactory.createAccount(collateral). The account address is deterministic and the call is idempotent — calling again returns your existing account. The collateral must be a configured, enabled token.
  • An account is bound to one owner and one collateral token. If you trade in more than one collateral, you get a separate account per collateral.
  • An account can hold up to a configured number of positions (capped at 32).
Cross positions settle directly into the account — proceeds from a close, reduce, or liquidation are credited to the account’s free collateral immediately. There is no separate claimSettlement step like there is for ordinary positions. Opening a cross position passes through the pool’s same new-risk gate as a direct open: a reduce-only market, a scheduled-closed market, or a market in its reopen grace window rejects cross opens too, and a hard pause blocks everything except claimSettlement.

​
Free collateral, equity, and margin

  • Free collateral is the account’s unallocated balance — collateral you have deposited that is not committed to a position. Deposit it with deposit; tokens sent to the account by other means are not counted until you call syncExcessCollateral.
  • Equity is your free collateral plus the current value of every active position: equity = free collateral + Σ position adjusted value. A losing position’s value is floored at zero, so it can drag equity down but never below zero on its own.
  • Each position adds an initial and a maintenance requirement, scaled from its exposure. Your account must keep equity ≥ initial requirement to open more or to withdraw, and it becomes liquidatable when equity < maintenance requirement.
You cannot withdraw freely: a withdrawal must leave the account still meeting its initial-margin requirement, so you can only take out the surplus above that. Withdrawals are blocked entirely while the account is being liquidated.

​
Account-level liquidation

Cross positions are not liquidated one-by-one through the pool. Instead the whole account is liquidated when equity < maintenance requirement. Anyone can trigger it through one of three permissionless entry points:
  • liquidate — fully close positions (newest first) until the account is healthy again.
  • liquidatePositions — fully close a specific set of the account’s positions.
  • liquidateToTarget — partially close selected positions just until equity recovers to a target margin level.
The liquidator’s incentive is paid out of your own free collateral — it is not charged on top, and there is no insurance fund and no socialized loss. The incentive is released gradually as the account’s shortfall shrinks. While an account is in liquidation, risk-increasing and capital-removing actions are blocked (you cannot withdraw, open, add collateral, add liquidity, or join a fee pool), but you can still reduce risk: close, reduce leverage, remove liquidity, or claim rewards. Depositing collateral is also allowed and automatically clears the liquidation once the account is healthy again.

​
Rescue collateral

If you deposit (or sync) collateral while the account is already liquidatable, that top-up is recorded as rescue collateral and excluded from the next liquidation’s incentive budget. This protects a last-second margin add from being handed straight to liquidators. The protection resets once the account is healthy again.

​
Trading through an app

Most users interact with their account through an app that routes calls via TACO’s trusted router. Before that works, the account owner must approve the router on the account once (setRouterApproval, called directly by the owner). LP lots held by the account are tracked for management but do not count toward account equity or margin — their value only re-enters the account when you remove the liquidity back to free collateral.

​
Trading agents (session keys)

You can authorize a trading agent — a hot key that opens and adjusts positions on your account without an owner confirmation per action, so an app can deliver a popup-free trading experience.
  • As the owner you authorize an agent with setTradingAgent(agent, expiry). This is owner-only and must be called directly on your margin account, never relayed through the router — it is a trust-root action like setRouterApproval. The expiry must be in the future, and you can have multiple agents authorized at once (for multiple devices or key rotation). Re-calling for the same agent extends, shortens, or rotates the key.
  • Revoke any agent instantly with revokeTradingAgent(agent), also owner-only. An agent is valid only while it is authorized and not past its expiry.
An authorized, non-expired agent may do only four things on your account: open a position, close a position, add collateral, and reduce leverage. It can never withdraw, change router approval, deposit, run any LP action, or manage agents — every one of those keeps the owner-only check and reverts for an agent. Agent-submitted orders must also carry keeperFeeAmount == 0: paying a keeper fee out of the account is owner-only, so an agent order with a non-zero account keeper fee reverts. Positions and payouts always belong to you, the owner — never the agent. The agent address is never recorded as the position’s trader or a recipient.
“Cannot withdraw” is not “cannot lose.” A compromised or buggy agent cannot move collateral to its own address, but within the expiry window it can open and close positions and erode the account’s at-risk balance — through losing or liquidating trades, fee churn, or trading on an attacker-created (but factory-genuine) pool whose creator recaptures the loss as creator/LP fees. Bound the blast radius: use short expiries, keep small balances in the account, and revoke promptly if a key is suspect. Prefer an ERC-1271 / passkey hot key over a raw exported EOA key.