> This is part 1 of 2 of the full documentation (pages 1–100 of 172). > The content is paginated: fetch every part to see all of it. > Next part: https://pacifica.gitbook.io/docs/llms-full.txt/1 > Page index: https://pacifica.gitbook.io/docs/llms.txt # About Us Pacifica was founded in January 2025 by a team of seasoned founders and builders who recognized the need for a next-generation trading platform that combines exceptional performance with user-first design principles and intelligent automation. Having witnessed the limitations of existing trading platforms - from poor execution speeds and high latency to suboptimal user experiences - we set out to build something different. Pacifica aims to deliver exceptional core trading performance through seamless user experience, enhanced by AI-powered smart trading tools that make sophisticated strategies accessible to everyone. We're not just building faster infrastructure - we're reimagining how trading should feel. Our core team brings together expertise from the world's leading crypto exchanges and protocols (Binance, FTX, Coinbase, NFTperp), top-tier financial institutions (Jane Street, Fidelity), and AI pioneers (OpenAI, DeepMind, ByteDance), with academic foundations from MIT, Stanford, NUS, and other leading institutions. This unique combination of traditional finance expertise, crypto-native experience, and cutting-edge AI capabilities positions us to solve the industry's core challenges: execution speed and quality, seamless user experience, and intelligent automation at scale. Building everything from scratch, we launched our testnet within 3 months and mainnet within 6 months - a testament to our execution speed and technical expertise. We build with best-in-class technical practices while maintaining the principles of transparency and user empowerment that define the future of finance.\ \ Pacifica has been self-funded throughout our journey. We haven't raised external capital, ensuring that all value created accrues directly to our users. # Close Beta Guide {% embed url="" %} # Testnet Guide {% embed url="" %} # Overview Pacifica supports perpetual and spot trading. Over thirty-five perpetual markets are currently listed, alongside a growing set of spot markets quoted in USDC. * **Instrument types:** Perpetuals and spot (base asset vs. USDC). * **Margin modes:** Cross margin (default; unified with spot collateral) and isolated margin. Spot is cross-only. * **Leverage:** 3x to 50x on perpetuals, depending on market. Spot is 1x. Detailed pages: * [Contract Specifications](/docs/trading-on-pacifica/contract-specifications) — perpetual contract specs and supported pairs. * [Oracle Price & Mark Price](/docs/trading-on-pacifica/contract-specifications/oracle-price-and-mark-price) * [Order Types](/docs/trading-on-pacifica/order-types) * [Margin & Leverage](/docs/trading-on-pacifica/margin-and-leverage) * [Unified Margin](/docs/trading-on-pacifica/unified-margin) * [Spot Collateral](/docs/trading-on-pacifica/spot-collateral) * [Spot Trading](/docs/trading-on-pacifica/spot-trading) * [Money Market](/docs/trading-on-pacifica/money-market) * [Funding Rates](/docs/trading-on-pacifica/funding-rates) * [Trading Fees](/docs/trading-on-pacifica/trading-fees) * [Deposits & Withdrawals](/docs/trading-on-pacifica/deposits-and-withdrawals) * [Liquidations](/docs/trading-on-pacifica/liquidations) *Access to Trading on Pacifica is strictly prohibited for individuals or entities residing in, incorporated in, or operating from, but not limited to, the United States of America, Cuba, the Crimean Peninsula (including Sevastopol), Iran, Afghanistan, Syria, and North Korea (collectively, the "Restricted Jurisdictions"). Access to trading functionality from IP addresses from any Restricted Jurisdiction is programmatically restricted.* # Contract Specifications Pacifica’s perpetual contracts let you seamlessly trade cryptocurrency assets with leverage, without the need for an expiration date. Understanding the specifications of these contracts is crucial for effective trading, risk management, and maximizing your trading potential. Below is a summary of Pacifica’s key contract details. You can explore deeper into each specification through dedicated subpages linked below. ### Pacifica Contract Specifications | Specification | Description | Details | | ------------------------------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Contract | Type of perpetual contract | Linear perpetual | | Contract Size | Size per contract | 1 unit of underlying spot asset | |

IMM
(Initial Maintenance Margin)

| Margin required to open a position | 1 / (user-selected leverage), dynamically increased when Open Interest sharply rises relative to liquidity | | MM | Maintenance Margin | 50% of initial margin fraction | | Dynamic Margin Adjustment | Margin requirement adjustments | Yes (triggered by sharp increase in open interest vs. exchange liquidity, super-linear scaling of initial margin) | | Oracle Price | Price used for liquidation & PnL | Oracle-based (see Oracle Price) | | Delivery / Expiration | Contract expiry | None (continuous with hourly funding payments) | | Position Limit | Maximum allowed position size | No explicit limit per user (position size managed by dynamic margining) | | Account Type | Margin management style | Per-wallet cross or isolated margin | | Funding Impact Notional | Notional size impacting funding rates | 20,000 USDC (BTC, ETH) 6,000 USDC (other assets) | | Maximum Market Order Value | Largest allowed market order | $4M (leverage >=50), $1M (leverage 20-50),$500k (leverage 10-20), otherwise $250k | | Maximum Limit Order Value | Largest allowed limit order | 10x— maximum market order value | ### Detailed Contract Information Explore further details for each area: * Trading Pairs: View all available perpetual markets. * [Oracle Price](/docs/trading-on-pacifica/contract-specifications/oracle-price-and-mark-price): Understand how Pacifica calculates the oracle-based Mark Price. *** Use this overview as your quick-reference guide, and dive deeper into each subpage for full explanations. # Supported Trading Pairs Pacifica currently supports trading of 20 pairs, with new markets regularly added based on community feedback, liquidity, and market demand. Our long-term vision is a fully decentralized and permissionless asset listing process driven entirely by the community. Leverage varies across assets, ranging from 5x to 50x, determined by each asset’s liquidity, volatility, and Pacifica’s dynamic risk management approach designed to prevent outsized liquidations and safeguard exchange stability (see [Margin & Leverage](/docs/trading-on-pacifica/margin-and-leverage)). The maintenance margin is always half of the initial margin required at the asset’s maximum leverage. For example, an asset with 20x maximum leverage (5% initial margin) would have a maintenance margin of 2.5%. ### Trading Pair Details You can view the complete list of supported trading pairs, along with asset-specific details such as maximum leverage, initial and maintenance margin requirements, and order value limits in the asset list below. * Download Supported Trading Pairs (CSV) Pacifica regularly updates this list based on market feedback, so please check back often or subscribe to announcements for updates. For questions or additional asset requests, reach out via our [Contact Us page](/docs/other/contact-us) or through our community channels. # Oracle Price & Mark Price Pacifica’s perpetual contracts use a decentralized Oracle Price to accurately value positions and determine funding rate and is a component of Mark Price. This Oracle Price protects traders by reducing manipulation risks and ensuring market stability. Mark Price is used for liquidations, margin requirements and Unrealized PnL. ### Oracle Price Calculation The oracle price is updated every 3 seconds and calculated as a weighted average of USDT denominated prices from major exchanges.
CEXWeights
Binance2
OKX1
Bybit1
Hyperliquid1
### Uses of Oracle Price on Pacifica The Oracle Price is crucial for several Pacifica exchange operations: * Funding Rates: Calculations rely on the Oracle Price to maintain alignment with spot markets. * Mark Price Calculation: Oracle price serves as a component of Mark Price to prevent market manipulation and ensure the accuracy of settlements. ### Uses of Mark Price on Pacifica The Mark Price is the median value of:\ 1\. Oracle (spot) price\ 2\. The median of best bid, best ask, and last trade on Pacifica\ 3\. Perpetual price from major exchanges The Mark Price is used for: * Liquidation Calculations: By using the median value of the 3 Mark Price components, Pacifica ensures fair and accurate liquidations. * Margin Requirements: Both initial and maintenance margins are determined using the Mark Price. * Unrealized PnL: Open positions are marked-to-market using the Mark Price. ### Transparency & Reliability Pacifica provides transparent and verifiable Oracle Prices available directly through our trading interface or via API endpoints, ensuring trust and accountability. *** For further details or technical questions, refer to our [API documentation](/docs/api-documentation/api) or contact our support via [Contact Us](/docs/other/contact-us). # Pre-Markets Pacifica uses an alternate mark and oracle pricing mechanic for pre-markets that are not listed on major exchanges. When Pacifica lists pre-markets that are not on other major exchanges, the oracle references Pacifica's mark price instead of external sources.\ \ An EMA is also applied to prevent oracle manipulation. This, combined with Pacifica's price band mechanic (+-30% of mark price) prevents extreme manipulation of pre-market perps.\ \ Once other major venues begin listing the same market, their pricing will be added to Pacifica's oracle reference in order to further strengthen its robustness.\ \ Additionally, Pacifica exercise strict open interest caps in pre-market pairs to prevent abnormal trading activity and market manipulation. # Settlement Mechanism Pacifica's contracts are continuously settled, meaning profits, losses, and funding payments are calculated and applied in real-time without an expiration date. Understanding this settlement mechanism is crucial for effectively managing your trades, margin, and risk. ### Funding Payments (Continuous Settlement) Pacifica uses **an hourly funding rate mechanism** to keep perpetual prices closely aligned with the underlying spot price: * **Positive funding rate:** Traders holding long positions pay traders holding short positions. * **Negative funding rate:** Traders holding short positions pay traders holding long positions. Funding payments occur automatically each hour and directly adjust your account balance. ### Realized & Unrealized PnL * **Realized Profit & Loss (PnL):** Realized PnL is calculated and applied immediately upon closing or partially closing a position. Profits or losses are instantly reflected in your trading balance. * **Unrealized Profit & Loss:** Unrealized PnL is continuously recalculated based on the [Oracle Price](/docs/trading-on-pacifica/contract-specifications/oracle-price-and-mark-price). It affects your margin and liquidation thresholds but only becomes realized when the position is fully or partially closed. ### Liquidation Settlement Pacifica employs a three-tiered liquidation process to manage positions falling below maintenance margin requirements: 1. **Initial liquidation attempt:** Positions are initially liquidated by sending market orders into the orderbook. If the position is sufficiently reduced to meet margin requirements, the remaining collateral stays with the trader. 2. **Backstop liquidation:** If the orderbook liquidity is insufficient to absorb the entire position without severely impacting the market, the position (along with remaining collateral) is transferred to the Pacifica backstop liquidation vault. The vault systematically manages position closure to minimize market disruption. 3. **Auto-Deleveraging (ADL) *****(last resort)*****:** Under extreme scenarios—such as very large positions significantly exceeding market liquidity—Pacifica employs Auto-Deleveraging, automatically closing opposing traders’ profitable positions based on risk priority to maintain overall market health. Any collateral remaining after liquidation fees and slippage are deducted is returned to the user’s account. If liquidation losses exceed the collateral available, losses are first absorbed by the liquidation vault, and in extreme scenarios, covered by ADL. ### Enhanced Settlement Safeguards at Pacifica In response to market incidents involving extreme position liquidations, Pacifica implements additional risk mitigation strategies within its settlement process: * **Dynamic Margin Requirements:** Pacifica dynamically adjusts initial and maintenance margin requirements based on open interest relative to orderbook liquidity. When large positions approach liquidity constraints, margin requirements automatically increase to ensure adequate collateral is retained. * **Withdrawal Restrictions During Extreme Volatility:** To prevent scenarios where traders withdraw collateral that might otherwise cover liquidations, Pacifica employs volatility-based withdrawal caps using an Exponentially Weighted Moving Average (EWMA) approach. During extreme market movements, traders may temporarily be unable to withdraw certain collateral amounts, reducing risk to the liquidation vault. ### Collateral Adjustments Collateral is continuously adjusted based on market prices and funding payments. This ensures accurate margin levels, liquidation thresholds, and fairness across all traders. ### Transparency & Verification Settlement details, including realized/unrealized PnL, funding payments, and liquidation transactions, are transparently visible in your transaction history and via Pacifica’s API. For further questions or clarifications, refer to our [API Documentation](/docs/api-documentation/api) or contact our support team via the [Contact Us](/docs/other/contact-us) section. # Order Types The following order types are available on Pacifica: * **Market:** An order that executes immediately at the best available market prices. Typically used in order to immediately enter or exit a position. * **Limit:** An order that specifies the price at which it will be executed. Limit orders can remain active based on different time-in-force settings (see below). Typically used when execution price matters more than being filled immediately * **Stop Market:** A market order that is placed when a price condition is met. Typically used to take profit or limit losses. * **Stop Limit:** A limit order that is placed when a price condition is met. **Time-In-Force:**\ All limit orders on Pacifica belong to one of the following TIF options. * **Good-Til-Cancelled (GTC):** The order remains active on the orderbook until it is either filled or cancelled. * **Immediate-or-Cancel (IOC):** The order attempts to match immediately at the specified price (or better). Any portion of the order that cannot is not filled immediately is cancelled. * **Add-Liquidity-Only (ALO):** Also known as **“Post Only,”** this order is added to the order-book only if it would does not immediately match against an existing order. * **Top-of-Book (TOB):** A special order type that allows "ALO (Post Only)" orders which cross the orderbook to be placed at the best bid/ask possible, instead of being cancelled. Best bid refers to lowest ask in orderbook minus one tick. Best ask refers to highest bid in orderbook plus one tick. \ Note: In order to protect liquidity providers from adverse selection, all market orders, TIF GTC, and TIF IOC orders are subject to a randomized 50-100ms delay. # Self-Trade Prevention Pacifica implements the following to prevent self-trading. When a new order attempts to match with a resting order placed by the same account, the existing order is cancelled, and the new order proceeds as per normal.\ \ This makes sure that no trades will happen between orders from the same account.\ \ The removed order will be labelled as "Rejected" under the "Status" column in order history. # Margin & Leverage *Account value and withdrawable balance now include spot collateral.* Pacifica supports cross margin and isolated margin. Margin mode is selected per trading pair. Cross margin is the default. Margin mode cannot be changed for a symbol with an open position. Leverage can be increased on a symbol with an open position but cannot be decreased until the position is closed. ### Cross margin Cross margin pools the account's USDC balance, unrealized PnL from cross perpetual positions, and LTV-adjusted spot collateral into a single equity figure that supports all cross positions. ``` account_value = usdc_balance + unrealized_pnl - pending_interest + spot_collateral_value ``` Unrealized PnL updates continuously. Isolated positions and their assigned margin are excluded. `pending_interest` is unsettled interest on any outstanding money-market borrow and is deducted from equity as soon as it accrues. Spot holdings contribute to `account_value` according to per-asset LTV, a per-user collateral cap, and an optional hedging bonus. See [Spot Collateral](/docs/trading-on-pacifica/spot-collateral) for the full formula. ### Isolated margin Isolated margin assigns a dedicated margin amount to each position. Isolated positions receive no collateral from spot holdings and are not affected by the unified margin model. Their liquidation is determined solely by the assigned isolated margin and the position's notional. ### Initial margin Placing an order reserves initial margin based on entry price, position size, and selected leverage. ``` initial_margin = position_size * entry_price / leverage ``` ### Unrealized PnL and withdrawable balance Unrealized PnL can be withdrawn from an isolated position or a cross-margin account, subject to the 10% initial-margin floor. Open spot buy orders also deduct their locked USDC from withdrawable balance: ``` withdrawable_balance = usdc_balance + unrealized_pnl - pending_interest + spot_collateral_value - max(initial_margin_required, 0.1 * total_position_value) - spot_buy_order_locked_usdc ``` # Unified Margin Cross margin extended to include spot holdings and implicit USDC borrowing. *Added as part of the unified margin rollout.* Unified margin is a generalization of cross margin across spot and per assets. Pacifica users' account's USDC balance, unrealized PnL, and spot holdings are margined together in a unified account. ### Account equity ``` equity_without_spot = usdc_balance + unrealized_pnl_from_cross_perps - pending_interest account_equity = equity_without_spot + spot_collateral_value ``` `pending_interest` is interest that has accrued on outstanding borrows but has not yet been settled against the USDC balance. It is deducted from equity the moment it accrues. See [Money Market](/docs/trading-on-pacifica/money-market). Spot collateral value is computed per asset using a piecewise curve based on LTV ratio, a per-user collateral cap, and an optional hedging bonus for delta-neutral positions. See [Spot Collateral](/docs/trading-on-pacifica/spot-collateral). ### Implicit borrowing Pacifica's implicit borrowing mechanism allows for greater capital efficiency when spot assets are used as margin for perpetual positions. Perp positions can be opened against spot margin with no initial borrow. The exception to this is isolated perp positions, where then entire margin required is borrowed upfront upon the position being opened. An account is treated as a borrower whenever `equity_without_spot < 0`. The shortfall `required_borrow = max(0, -equity_without_spot)` is covered implicitly by the money market. This can happen because the USDC balance goes negative, cross perp losses exceed USDC, or accrued interest pushes equity below zero. Interest accrues on the outstanding amount from that point. No user action is required, and no explicit borrow transaction is submitted. Implicit borrowing only proceeds if the account holds enough spot collateral to cover the borrow under effective LTV. An account without adequate spot collateral is flagged for deleveraging. See [Liquidations](/docs/trading-on-pacifica/liquidations#spot-insolvency-deleveraging). ### Carry and hedged positions Because spot and perpetual PnL are netted in a single equity figure, a long spot position paired with a short perpetual on the same underlying functions as a carry trade without requiring the user to collateralize each leg separately. The matched portion of the hedge also receives an elevated LTV rate. See [Spot Collateral](/docs/trading-on-pacifica/spot-collateral). ### Exceptions to Unified Margin * A spot asset can be excluded from unified margin at the account level by setting `unified_margin_excluded` (this can be done on the portfolio page). The balance remains usable for spot trading but contributes zero collateral for perpetual margining. * Assets with `collateral_enabled = false` never contribute collateral regardless of account settings. (currently all spot assets contribute collateral) ### Sub-accounts Sub-accounts are margined independently. Spot collateral and USDC held in a sub-account back only that sub-account's positions. Assets can be moved between a master account and its direct sub-accounts via [subaccount spot transfers](/docs/trading-on-pacifica/deposits-and-withdrawals#subaccount-spot-transfers). # Portfolio Margin Testnet only ## Pacifica Unified Margin Pacifica uses a **unified margin system** where cross-margin perpetual positions and spot collateral are margined together in a single account. This design maximizes capital efficiency while removing the need for explicit lending or borrowing actions by users. There is **no separate lending vault**. Instead, the system automatically forms a **global USD loan pool** from users’ idle USD balances. Borrowing and lending happen implicitly as part of normal trading activity. *** ### How the Global Loan Pool Works #### Lenders (Loan Pool) * There is no explicit supply or deposit action required. * The loan pool is formed from each account’s [available-to-withdraw USDC balance](https://docs.pacifica.fi/trading-on-pacifica/margin-and-leverage) * Only accounts with available-to-withdraw balances above the minimum threshold (currently 1,000 USDC) are included. * Any account meeting the threshold is automatically a lender and earns interest. #### Borrowers * An account becomes a borrower when its cross-margin equity (USDC balance + unrealized perp PnL) < 0 * The required borrow amount per account is calculated by the following: ``` required_borrow = max(0, -cross_margin_equity) ``` * Borrowing is implicit. When the user’s USD balance becomes negative in accounting terms, it is covered by the pool, and interest is paid on the negative amount. #### Settlement and Assets * **USDC:** * Only ever used as the borrowed asset. * All interest payments are settled in USDC * **Spot assets:** * Act as collateral only * Subject to LTV * Never borrowed or lent (no rehypothecation) *** ### Capital Efficiency and Collateral Unified margin enables significantly improved capital efficiency on Pacifica, and unlocks many additional strategies such as basis trades to be executed: * Spot collateral can support perp positions * Collateral value and perp PnL offset each other * Trading, borrowing, and repayment all settle into a single USD balance #### Spot Collateral & LTV * Each eligible spot asset has the following attributes: * `collateral_enabled` * `ltv_ratio` (between 0 and 1) * Spot collateral value contributes to total account equity and borrowing capacity. * Spot collateral withdrawals are limited by the following: ```worktree-rust available_to_withdraw = min(spot_balance,(total_collateral - borrow_amount) / (price × ltv_ratio)) ``` *** ### Interest Model #### Accrual * Interest accrues every minute * For each borrower ``` interest_accrued = borrow_size × borrow_rate_per_second × elapsed_seconds ``` #### Payout Every hour: 1. Borrowers are charged based on `interest_accrued` over the last hour 2. Lenders are paid pro-rata based on their share of total borrowable USD *** ### Utilization and Borrow Rates Utilization percentage is used to calculate the borrow rate ``` utilization = total_borrowed / total_borrowable ``` #### Borrow Rate Curve (APR) Borrow APR follows a **piecewise curve**: 1. **Below optimal utilization** (e.g. 80%) * Linear increase from: * Minimum APR (e.g. 1%) * To kink APR (e.g. \~10.95%) 2. **Above optimal utilization** * Rate increases exponentially * Approaches a capped APR (e.g. 50%) All constants are defined in: ``` common/src/loan_pool.rs ``` (e.g. `DEFAULT_MIN_BORROW_APR`, `DEFAULT_OPTIMAL_UTILIZATION`, etc.) *** ### Liquidations and Insolvency Unified margin is a generalization of cross margin. All cross-margin perps and spot collateral are evaluated together. **Sub-accounts are isolated.** #### Loan Insolvency Checks A background worker (`CheckLoanInsolvency`) runs periodically (e.g. every 10 seconds) to detect: * Accounts whose collateral is insufficient to support borrow and margin * Excessive pool utilization (e.g. > 95%) #### Auctions When needed, the system opens **spot collateral auctions**: * **Account-level auctions:**\ Restore a specific account to a safe state * **Pool-level auctions:**\ Reduce utilization back to a target (e.g. from 95% → 90%) by selling collateral from the largest borrowers Auction flow: * `OpenAuction` * `BuyAuction` * Buyers pay USD * Sellers receive proceeds minus auction fees There is no separate “portfolio margin ratio”; insolvency is driven by: * Equity vs required margin * Pool utilization constraints #### Order Restrictions * If a user is already borrowing **and** * Pool utilization exceeds a threshold (e.g. 90%) Then **non-reduce-only orders may be blocked** to prevent further strain on the pool. *** ### Precision and Accounting * **USD precision:** `DECIMAL(24,12)` * All accruals and payouts are computed in full precision * Rounding is resolved deterministically during lender payout * Interest is: * Accrued every 60 seconds * Paid out every 1 hour *** ### API & Monitoring #### REST * `GET /api/v1/loan_pool`\ Pool aggregates and derived `borrow_rate_apr` * Spot assets, withdrawals, and auctions: * `GET /api/v1/spot_assets` * Auction list / details #### gRPC * Spot operations: * `AddSpotAsset` * `WithdrawSpotAsset` * `DepositSpotAsset` (test/admin) * Auctions: * `OpenAuction` * `BuyAuction` Accrual, payout, and insolvency are handled by system workers, not user RPCs. #### WebSocket * Auction updates * Account stats (e.g. spot balances, `pending_interest`) *** ### Comparison: Unified Margin vs Supply-Based Lending | Feature | Pacifica Unified Margin | Supply-Based Lending | | --------------- | ---------------------------------- | -------------------------- | | Lendable funds | Idle USD (`available to withdraw`) | Explicit supplied assets | | User opt-in | None | Required | | Borrowed asset | USD only | Asset-specific (e.g. USDC) | | Collateral | Spot assets with LTV | Collateral assets with LTV | | Interest payout | Hourly, pro-rata | Protocol-specific | *** For implementation details, schemas, and workers, see # Spot Trading Spot markets quoted in USDC on the shared orderbook. Spot markets trade a base asset against USDC on Pacifica's performant orderbooks. ### Order types Spot markets accept Market, Limit, Stop Market, and Stop Limit orders with TIF settings GTC, IOC, ALO, and TOB. See [Order Types](/docs/trading-on-pacifica/order-types) for more. Orders flagged `reduce_only` on a spot market are rejected. ### Fees Spot fees are deducted from the received asset at the end of a trade. ``` buy: received_base = (usdc_spent / price) * (1 - fee_rate) sell: received_usdc = (base_sold * price) * (1 - fee_rate) ``` Fee tiers follow the perpetual fee schedule. See [Trading Fees](/docs/trading-on-pacifica/trading-fees). ### Balance locks Placing a spot order locks the relevant balance until the order fills or is cancelled. | Side | Locked balance | Effect on cross margin | | ---- | ---------------------- | ---------------------------------------------------------------------------- | | Buy | `size * price` in USDC | Reduces `available_to_spend` and `available_to_withdraw` by the locked USDC. | | Sell | `size` in base asset | Reduces `spot_collateral_value` by the locked units' LTV-adjusted value. | # Spot Collateral Rules for valuing spot holdings as cross-margin collateral. *Added as part of the unified margin rollout.* Each eligible spot asset contributes collateral to a cross-margin account according to four per-asset parameters. The contribution is bounded by a per-user USD cap on market value and may be boosted for the portion of the balance hedged by an opposing cross-margin short. ### Parameters | Parameter | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `collateral_enabled` | If false, the asset contributes zero collateral regardless of balance or settings. | | `ltv_ratio` | Loan-to-value ratio, between 0 and 1. Typical values: 0.90 (BTC, ETH), 0.80 (majors). | | `spread_divisor` | Hedging bonus multiplier applied to the hedged portion of a balance. Optional. Bonus applies only when `spread_divisor > 1`. | | `collateral_value_limit_usd` | Per-(user, asset) cap on the asset's gross market value that is eligible for collateral. Default 10,000 USD. | Parameter values are published via `GET /api/v1/spot_assets`. The per-user cap can be raised by admin override. ### Collateral curve For spot balance `B`, oracle price `P`, and hedged size `H` (the portion of `B` offset by a cross-margin short perpetual in the same underlying; isolated shorts do not count): ``` base_rate = ltv_ratio * P bonus_rate = P * (1 - ltv_ratio) * (1 - 1 / spread_divisor) (when spread_divisor > 1, else 0) hedged_rate = base_rate + bonus_rate capped_units = collateral_value_limit_usd / P hedged_units = min(H, B, capped_units) base_units = min(B, capped_units) - hedged_units spot_collateral_value = hedged_rate * hedged_units + base_rate * base_units ``` Units beyond `capped_units` contribute no additional collateral; they remain in the account and are fully tradeable. Because `capped_units` is defined in terms of market value, the maximum collateral a single (user, asset) pair can contribute to cross margin is `ltv_ratio * collateral_value_limit_usd` (e.g. 9,000 USD at `ltv_ratio = 0.9` and the 10,000 USD default cap). ### Hedging bonus example SOL with `ltv_ratio = 0.80`, `spread_divisor = 1.05`, `P = 150`. Account holds 100 SOL spot and a 50 SOL cross-margin short perpetual. Assume the balance is below the per-user cap. ``` base_rate = 0.80 * 150 = 120 bonus_rate = 150 * (1 - 0.80) * (1 - 1/1.05) ≈ 1.4286 hedged_rate = 120 + 1.4286 ≈ 121.4286 hedged_units = 50 base_units = 50 spot_collateral_value ≈ 121.4286 * 50 + 120 * 50 ≈ 12,071.4 ``` Without the hedge, the same 100 SOL would contribute `120 * 100 = 12,000`. The hedge adds roughly 71.4 USD of additional collateral. ### Spot sell orders Placing a spot sell order locks the base asset against the order. Locked units are excluded from `spot_collateral_value` until the order fills or is cancelled. See [Spot Trading](/docs/trading-on-pacifica/spot-trading#balance-locks). ### Excluding an asset from unified margin Setting `unified_margin_excluded = true` on a (user, asset) pair removes its collateral contribution. The balance remains in the account and can be bought, sold, withdrawn, or transferred normally. # Money Market USDC lending and borrowing integrated into the cross-margin account. *Pacifica operates a single USDC money market shared across all cross-margin accounts* Lending and borrowing are implicit on Pacifica. Positions can be opened against spot collateral and pay no interest until negative PnL triggers a borrow. Accounts with idle USDC above a threshold supply the pool and earn interest. Accounts who 1) hold spot collateral 2) have cross margin equity that falls below zero automatically borrow from the pool and pay interest. Only USDC is lent or borrowed; spot assets serve as collateral and are never rehypothecated. ### Lenders and borrowers An account is eligible to lend when all of the following hold: * Its USDC balance is at least the minimum lender threshold (1,000 USDC). * Its lendable capacity — USDC balance net of the 10% initial-margin floor, pending interest, and any USDC locked by spot buy orders — is also at least 1,000 USDC. * `auto_lend_disabled` is false. An account is a borrower when: ``` equity_without_spot = usdc_balance + unrealized_pnl_from_cross_perps - pending_interest required_borrow = max(0, -equity_without_spot) ``` and `required_borrow > 0`. Borrowing is only permitted while spot collateral is sufficient to cover the shortfall. An account without adequate spot collateral is flagged for insolvency deleveraging. See [Liquidations](/docs/trading-on-pacifica/liquidations#spot-insolvency-deleveraging). ### Pool aggregates ``` total_borrowable = sum over eligible lenders of their lendable capacity total_borrowed = sum over borrowers of required_borrow utilization = total_borrowed / total_borrowable ``` Pool state is published via `GET /api/v1/loan_pool`. ### Utilization thresholds | Threshold | Utilization | Behavior | | ------------------------ | ----------- | --------------------------------------------------------------------- | | Optimal | 80% | Borrow APR equals the kink rate. | | Order admission limit | > 90% | Borrowing accounts cannot place new non-reduce-only perpetual orders. | | Pool deleveraging | ≥ 95% | Pool-level insolvency deleveraging begins. | | Pool deleveraging target | 90% | Utilization target after pool-level deleveraging. | ### Borrow APR Borrow APR is a piecewise function of utilization: ``` u <= 0.8: apr = MIN_BORROW_APR + (LINEAR_KINK_APR - MIN_BORROW_APR) * (u / 0.8) u > 0.8: apr = LINEAR_KINK_APR * (EXPONENTIAL_TARGET_APR / LINEAR_KINK_APR) ^ ((u - 0.8) / 0.2) ``` Current defaults: `MIN_BORROW_APR = 1%`, `LINEAR_KINK_APR = 10.95%`, `EXPONENTIAL_TARGET_APR = 50%`. At `u = 1`, the curve reaches exactly `EXPONENTIAL_TARGET_APR`. Lender APR is derived pro-rata from utilization: ``` lend_apr = borrow_apr * utilization ``` APR values are compounded per-second, so `APY ≈ e^APR - 1`. ### Interest accrual and payout Every 60 seconds, each borrower's `pending_interest` grows by: ``` pending_interest += required_borrow * borrow_rate_per_second * 60 ``` Every hour, accumulated `pending_interest` is charged to the borrower's USDC balance and distributed pro-rata across lenders' USDC balances. ### Order admission under stress When pool `utilization > 90%`, accounts carrying a borrow (`equity_without_spot < 0`) cannot place new perpetual orders unless the order is reduce-only. Spot orders are not subject to this check. Non-borrowing accounts are unaffected. ### Opt-outs * **Stop lending.** Set `auto_lend_disabled = true`. USDC balance remains usable for trading but is excluded from `total_borrowable` and earns no yield. * **Exclude a spot asset from unified margin.** Set `unified_margin_excluded = true` on a (user, asset) pair. The asset remains in the account and tradeable but contributes no collateral and cannot back a borrow. Borrowing itself cannot be disabled. An account whose `equity_without_spot` drops below zero with sufficient spot collateral will automatically open a loan. # Funding Rates Funding fees ensure perpetual contract prices closely track the underlying spot market. Depending on the prevailing funding rate, traders with open positions periodically pay or receive these fees: * Positive Funding Rate: Traders holding long positions pay traders holding short positions. * Negative Funding Rate: Traders holding short positions pay traders holding long positions. Funding rates are updated every hour, calculated based on market conditions from the previous hour. ### Funding Rate Calculation Pacifica calculates the funding rate using two components: the Premium Index and a fixed 8-hour Interest Rate (0.01%): ``` funding_rate = (premium_index + clamp(interest_rate - premium_index, -0.05%, 0.05%))/8 ``` **Where:** * **Premium Index** measures the deviation between the Impact Price and the Oracle Price: ``` premium_index = impact_price / oracle_price - 1 ``` * **Impact Price** is determined by the average execution price for a defined Impact Notional from Pacifica’s orderbook: ``` impact_price = max(impact_bid_price - oracle_price, 0) - max(oracle_price - impact_ask_price, 0) ``` The **Impact Notional** values are:
AssetImpact Notional (USD)
BTC$20,000
Other$6,000
* **Clamp** of +-0.05% keeps funding static for small fluctuations in premium, allowing for a steady funding rate during relatively steady market conditions Pacifica samples and updates the funding rate every **5 seconds** and displays a TWAP of the estimated next 1h funding rate. At the end of each **1-hour interval**, the average funding rate is taken and then applied to open positions, and the funding rate TWAP is reset. Funding fees per hour are capped at ±4%.\ \ **Funding payments:** * Long positions: * Positive funding rate: Account Balance reduced (pay fee) * Negative funding rate: Account Balance increased (receive fee) * Short positions: * Positive funding rate: Account Balance reduced (receive fee) * Negative funding rate: Account Balance increased (pay fee) ### Effect on Isolated Positions and Liquidations For isolated margin positions, funding payments are deducted from the isolated margin balance and will therefore affect the position's liquidation price. After each funding payout, Pacifica recalculates liquidation prices to reflect the adjusted margin. # Trading Fees Pacifica's Fee Tiers. Your trading volume on Pacifica determines your fee tier.\ \ Fees tiers update daily based on an account's volume over the past 14 days.\ \ All subaccounts share the same fee tier as the master account.\ Subaccount volumes count toward the master account total for fee calculations. | Tier | 14-day Rolling Volume | Maker Fee | Taker Fee | | ----- | --------------------- | --------- | --------- | | 1 | 0 | 0.015% | 0.040% | | 2 | > $5,000,000 | 0.012% | 0.038% | | 3 | > $10,000,000 | 0.009% | 0.036% | | 4 | > $25,000,000 | 0.006% | 0.034% | | 5 | > $50,000,000 | 0.003% | 0.032% | | VIP 1 | > $100,000,000 | 0.000% | 0.030% | | VIP 2 | > $250,000,000 | 0.000% | 0.029% | | VIP 3 | > $500,000,000 | 0.000% | 0.028% | Note: * All volume thresholds refer to your total executed trading volume in USD equivalent. * Fees are settled automatically for each trade upon execution. # Liquidations *Updated as part of the unified margin rollout. A Spot Insolvency Deleveraging section has been appended. Perpetual liquidation behavior is unchanged.* Pacifica employs a three-tiered liquidation process to manage positions that fall below the required maintenance margin. The multi-step approach minimizes market disruption while ensuring that a trader's collateral is used effectively to cover losses. ### Liquidation Price Formula Liquidation occurs when a user's account equity falls below the maintenance margin of open positions. Maintenance margin is ½ the initial margin requirement on all markets, defined by `1 / max_leverage` of the market. ``` liquidation_price = [price - (side * position_margin) / position_size] / (1 - side / max_leverage / 2) ``` `side = 1` for long, `-1` for short. `position_margin` is `account_equity` for cross-margin positions; `price` should be the current `mark_price` if `account_equity` already reflects unrealized PnL. ### Three-tiered liquidation process 1. **Market Liquidation.** When a user's account equity first falls below maintenance margin but remains above the backstop liquidation threshold (⅔ of maintenance margin), all open orders — including ones that would otherwise reduce exposure — are cancelled, and the positions are liquidated by sending market orders into the orderbook. During a market liquidation, positions are broken into smaller chunks, each placed as an IOC order as close to backstop liquidation price as possible (to prevent immediate backstop liquidation). The chunking strategy is dynamic and based on market leverage: ``` Small positions (< $2,000 * max_leverage): 1 chunk (immediate) Large positions (>= $2,000 * max_leverage): 5 chunks ``` `max(0.75%, maintenance_margin_ratio * 0.4)` of the value of positions liquidated in this manner is deducted by the liquidation engine. Large positions are sent with a small interval between chunks (average under 1 second). If enough of the position is closed to restore maintenance margin levels, the remainder stays with the trader as a partial liquidation. 2. **Backstop Liquidation.** If account equity falls below ⅔ of the maintenance margin, all open positions and remaining collateral are transferred to a Pacifica backstop liquidator. This prevents orderbook disruption during large market movements. 3. **Auto-Deleveraging.** If account equity falls below zero while maintaining an open position — caused by prior tiers having insufficient liquidity — Pacifica closes opposing profitable traders' positions based on risk priority to maintain overall market health. Due to their experimental or volatile nature, the backstop liquidator does not take positions from the following markets: `URNM, GOLD, SILVER, PAXG, CL, COPPER, NATGAS, EURUSD, USDJPY, NVDA, TSLA, PLTR, SP500, GOOGL, CRCL, HOOD, MEGA, BP`. ### Spot Insolvency Deleveraging *Added as part of the unified margin rollout.* Unified margin accounts can hold negative USDC balances backed by spot collateral. A separate deleveraging path unwinds spot positions if an account's debt exceeds its collateral or if the money market is under stress. This is a seperate from perpetual liquidations. Spot deleveraging runs in two modes: 1. **Account-level.** Triggered when an individual borrower's spot collateral value is no longer sufficient to support the USDC debt and/or any perpetual initial-margin requirement. 2. **Pool-level.** Triggered when money-market `utilization >= 95%`. Deleveraging proceeds from the largest borrowers first and aims to bring utilization back down to 90%. In both modes, the system begins liquidating spot assets the account's behalf into the spot orderbook to repay USDC loans. # Deposits & Withdrawals *Updated as part of the unified margin rollout. Spot asset deposits/withdrawals and subaccount spot transfers are documented below. USDC content is unchanged; one clarification on withdrawal gating under unified margin is added.* Before trading, a user connects a Solana-compatible wallet to Pacifica and funds the account with USDC. Pacifica supports Phantom, Solflare, Backpack, Ledger (via browser extension), and other WalletConnect-compatible wallets. ## USDC Deposits Pacifica currently limits deposits to a maximum of $250,000 account equity during Closed Beta. Additional deposits are gated on the frontend, and API deposits exceeding these amounts are held in pending. Minimum deposit: $10. Fees: network gas only. ### USDC Withdrawals Pacifica currently limits single-account withdrawals to a maximum of $250,000 every 24 hours during Closed Beta. Additional withdrawals are gated on the frontend, and API withdrawals exceeding the limit are held in pending. Unrealized PnL may be withdrawn from an isolated position or a cross-margin account subject to the 10% initial-margin floor. See [Margin & Leverage](/docs/trading-on-pacifica/margin-and-leverage). An exchange-wide withdrawal cap applies across all assets as a risk-mitigation mechanism. It is unlikely to affect normal withdrawals. Under unified margin, USDC withdrawal is bounded by `available_to_withdraw`, which deducts any outstanding money-market borrow. An account with a negative USDC balance cannot withdraw USDC until the debt is repaid or sufficient spot is sold. Minimum withdrawal: $1. Fees: $1 per withdrawal (gas). ## Spot Asset Deposits *Added as part of the unified margin rollout.* Spot assets are credited to the account after on-chain confirmation. Once credited, the balance is tradeable on the corresponding spot market and contributes cross-margin collateral per the asset's LTV and per-user cap. See [Spot Collateral](/docs/trading-on-pacifica/spot-collateral). Each supported spot asset has a per-user daily USD-notional deposit cap of $50,000. Minimum deposit: approximately $10 worth of the deposited asset. Fees: network gas only. ## Spot Asset Withdrawals The maximum withdrawable amount for a given spot asset is: ``` available_spot_to_withdraw = min(spot_balance, (cross_equity_without_spot + spot_collateral_value - required_borrow - 0.1 * total_position_value) / (price * ltv_ratio)) ``` The constraint ensures remaining collateral covers both outstanding perpetual margin and any money-market debt after withdrawal. The 10% floor on `total_position_value` matches the constraint applied to USDC withdrawals. Each asset has a per-user daily USD-notional withdrawal cap of $250,000. Requests above the cap are queued for the next reset. A time-based, exchange-wide withdrawal cap applies across USDC and spot combined. Fees: network gas, plus a withdrawal fee of approximately $1 worth of the withdrawn asset. ## Subaccount Spot Transfers *Added as part of the unified margin rollout.* Spot assets can be moved between a master account and any of its direct subaccounts without an on-chain transaction. Transfers are instant and fee-free. Asset movements are subject to margin requirements. USDC transfers between subaccounts continue to follow the existing [Subaccount Fund Transfer](/docs/api-documentation/api/rest-api/subaccounts/subaccount-fund-transfer) rules. # Fund Security Forging the future of perpetual DEX security: hot-cold hybrid fund protection In the high-stakes world of decentralized finance, security is the foundation upon which everything else is built. At Pacifica, our mission has always been to build the most powerful and secure perpetual DEX, one that rivals the performance of centralized exchanges without sacrificing the self-custodial ethos that makes DeFi revolutionary. Since our mainnet launch we have processed significant volume, earning the trust of a rapidly growing community of active traders. This trust is our most valuable asset. In order to keep up with the continuously raising stakes of growth, Pacifica is transitioning to a sophisticated hot-cold hybrid security architecture with multi-signature governance. ## The Inherent Tension: Power vs. Protection The core challenge for any high-performance perpetual DEX is managing the "withdrawal authority", the logic within a smart contract that permits the movement of user funds. To facilitate instant withdrawals, this authority must be readily accessible to the matching engine. However, concentrating this access in a single, always-online endpoint creates systemic risk. Most perpetual DEXs operate with a unified smart contract architecture where all user funds reside in a single upgradeable contract. In these systems, the proxy contract holds user funds and delegates calls to a logic contract. If administrators can upgrade this logic, they possess the ability to modify withdrawal permissions. The contract logic is flexible, but ultimate control rests with whoever holds the admin keys. If the withdrawal authority is compromised, all funds are exposed. Subsequent effects of this are then: if the smart contract has a vulnerability, all funds are at risk, and if admin keys are stolen, the contract logic itself can be upgraded to drain user capital. There's no segmentation, no firebreak, no defense in depth. ## The Pacifica Protocol: Layered, Proactive Security We aim to think beyond this single-point-of-failure paradigm entirely. Our new design creating a multi-layered defense system that is both resilient and non-custodial. This is the culmination of best practices implemented in a transparent, verifiable manner. ### The Hot Wallet: The Engine of Commerce This is the operational treasury and represents only a fraction of total funds. The hot wallet is managed by the matching engine, which can execute withdrawals up to the programmatic spending limit without additional approvals. This ensures legitimate user withdrawals remain instantaneous. If compromised through an engine key breach, smart contract exploit, or social engineering attack, an attacker can only access the limited funds in the hot wallet. ### The Cold Vault: The Fortress of Funds The bulk of user capital resides in the cold vault, secured by a multi-signature smart contract governed by a decentralized council that is geo-distributed across multiple continents. This vault has one primary function: to replenish the hot wallet through programmatic spending limits. We've partnered with Squads Protocol, the leading multi-signature infrastructure securing over $10 billion in assets on Solana. Squads is the first formally verified program on Solana, meaning its code has undergone mathematical proofs of correctness beyond traditional auditing. The multi-signature requirement means multiple independent parties must approve any transaction before it executes, eliminating the single point of failure inherent in traditional single-key wallets. Squads enables time-locked upgrade mechanisms that introduce mandatory delays between proposal and execution, giving users visibility and the ability to exit if they disagree. Role-based access control defines who can propose, approve, and execute transactions. Emergency pause functionality requires multi-party consensus. The cold vault cannot send funds to arbitrary addresses. Its logic is constrained by design, making it technically impossible for any party to redirect funds elsewhere. ### The Unbreakable Chain of Custody The true innovation lies in the interaction between these two layers, creating a security model that provides both operational efficiency and ironclad protection. When a user requests a withdrawal, the matching engine processes it instantly from the hot wallet. If the hot wallet balance dips below a predefined threshold, a replenishment process is automatically initiated, which requires a consensus-approved transaction from the decentralized multi-sig governing the cold vault. Multiple independent signers must review and approve the transfer, ensuring that no single party can unilaterally move funds from cold storage. The cold vault then sends only the necessary amount to replenish the hot wallet up to its operational limit, never exceeding the predetermined cap. This creates a security guarantee: even in a worst-case scenario where our operational systems are fully compromised, where an attacker gains control of the matching engine, the AWS infrastructure, or even internal access credentials, they can only access the limited funds in the hot wallet. The majority of funds remain safe. Using Squads' programmatic spending limit feature, we can allocate specific withdrawal budgets to the hot wallet without requiring full multi-signature approval for every routine operation. For example, the hot wallet might have a daily limit of $5 million USDC for user withdrawals. Any attempt to exceed this limit automatically triggers multi-signature requirements. The system is self-enforcing; the blockchain itself prevents unauthorized fund movements. ### Signer-Level Separation: The Technical Advantage Our architecture implements security at the signer level, creating distinct roles with different permissions and capabilities. The hot signer, controlled by the engine operator, can withdraw up to the Squads wallet's spending limit in a specified time duration. The cold signers, a distributed group of multi-sig members, control reserve funds and have the authority to adjust spending limits through consensus. The upgrade authority is distributed across multi-sig participants, not held by any individual or single organization. This means any single party attempting to compromise the exchange, whether external attacker or rogue insider, can only access the limited funds in the hot wallet. The spending limit acts as a firebreak, containing potential damage and preventing catastrophic loss. Let's examine potential attack scenarios:
Attack VectorSingle ContractPacifica Hot/Cold Hybrid
Engine compromiseAll funds exposedOnly hot wallet funds exposed
Smart contract exploitAll funds at riskOnly hot wallet funds at risk
Admin key compromiseCan upgrade to drain all funds

Requires multi-sig;

spending limits enforced

Social engineeringSingle point of failureMultiple parties must be compromised
Inside threatUnilateral access possibleImpossible without multi-party collusion
### Uncompromising Decentralization By vesting control of the cold vault in a decentralized multi-sig, we eliminate any single point of failure's ability to bring down the entire system. The distributed governance model ensures that even if several parties are compromised, the threshold mechanism prevents unauthorized access to the majority of funds. ### Verifiable Security Over Blind Trust Our model allows the community to audit the key facts: the spending limit of the hot wallet and the immutable logic of the cold vault. You don't have to trust us; you can verify the security model on-chain. Every parameter, every threshold, every authorization is recorded on the blockchain and can be independently verified by anyone. Any proposed change to withdrawal authorities or spending limits requires not only multi-signature approval but also a time-locked execution period, giving users visibility into governance decisions and the ability to withdraw their funds if they disagree. Pacifica's bridge and cold vaults, along with all component logic can be found in the following addresses: USDC deposit/withdraw bridge: `72R843XwZxqWhsJceARQQTTbYtWy6Zw9et2YV4FpRHTa` SOL deposit/withdraw bridge: `9sSr35zwnFTuv2kZ86i55sR9dqQLTG663homexrLYgYu` USDC cold-vault: `5kwCMKjE3Krvs7cHfcQ9kBkGyPQphd3oJ4KnsXcpMoVc` SOL cold-vault: `8nFeyzTFhUXp11raJkSSvZWn9GXDjcrGq8LuzP9aKtg8` ### Built for Scale This architecture is designed to grow with us. As our TVL expands into the hundreds of millions and even billions, the risk profile remains constant. Whether we're securing $100 million or $10 billion in user funds, the fundamental security guarantees remain unchanged: the hot wallet cap limits exposure, the multi-sig prevents unauthorized cold storage access, and the spending limits act as an automatic circuit breaker. ## Conclusion: Security as a First Principle The transition to hot-cold hybrid architecture with multi-signature governance and programmatic spending limits represents more than a technical upgrade. It's a statement that we prioritize long-term security over short-term convenience, and that decentralized finance can meet the highest security standards while exceeding centralized platforms in transparency and verifiability. As we continue scaling toward becoming the leading perpetual DEX, security architecture that protects billions in user funds lays an ironclad foundation. We build for the future. # Overview User-deployed managed pools that trade on Pacifica. A vault is a managed trading pool deployed by a Pacifica user. Depositors contribute USDC; a designated manager (vault manager) trades the pooled balance on Pacifica. Profits and losses are distributed to depositors according to the vault's configuration. A vault is a real Pacifica trading account, and is subject to the same Margin, leverage, mark-price, and trading rules by default. The vault's balance, however, is collectively owned by its depositors via shares. The trading actions the manager can take is additionally bounded by configurable trading constraints set at vault creation. ### Roles | Role | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Creator** | The address that calls `create_lake` and pays the creation fee. The creator chooses the vault's configuration and can later update a small set of post-creation–mutable parameters. | | **Manager** | The address authorized to place orders for the vault. Set at creation, or claimed afterward via `claim_lake_manager` on a manager-less vault. The manager also deposits capital and holds Manager Shares. | | **LP / Depositor** | Any address that deposits into the vault. Receives LP Shares proportional to the vault's NAV at deposit time. | The creator and manager may be the same address, different addresses, or — for a fresh vault — the manager seat may be left open for a third party to claim later. ### Share classes A vault tracks two independent share classes against the same pool of capital: * **Manager Shares** are minted when the manager deposits and burned when the manager withdraws. They give the manager a claim on the manager-side balance and route their share of profits/losses through the manager's economics (including the performance fee on profits above the high-water mark). * **LP Shares** are minted to any other depositor and follow the LP-side balance. Each share class has its own `balance` and `share count`, but both classes own a single underlying account balance and a single set of positions. PnL is split between the two classes pro-rata before any per-class economics apply. See [Profit & Loss](/docs/vaults/profit-and-loss). ### Lifecycle 1. **Create.** Creator pays the creation fee and chooses a configuration. The vault is assigned a fresh address and starts empty. 2. **Seed.** The creator may seed the vault in the same call, or the manager (if different) may deposit later. A vault with `manager_min_balance_portion` set must satisfy that floor before LP capital is accepted by the deposit cap. 3. **Operate.** The manager places orders for the vault subject to its symbol whitelist, blacklist, and per-symbol leverage caps. LPs deposit and withdraw within the configured cooldowns and withdrawal windows. 4. **Halt or wind-down.** If the manager's balance share falls below the configured liquidation portion, the engine halts trading and liquidates open positions. The manager can lift the halt by depositing back to the minimum balance portion. A vault with no remaining capital can be left dormant indefinitely. ### Per-page guide * [Depositing](/docs/vaults/depositing) — for users putting USDC into a vault. Covers share accounting, withdrawals, and what to evaluate before depositing. * [Managing a Vault](/docs/vaults/managing-a-vault) — for vault creators and managers. Covers configuration, mutability, and operating constraints. * [Profit & Loss](/docs/vaults/profit-and-loss) — how PnL is distributed between LP and Manager Shares, the performance fee, and the high-water mark. * [Risk Controls](/docs/vaults/risk-controls) — symbol whitelists, leverage caps, manager balance requirements, trading halt, and vault liquidation. # Depositing into a Vault How deposits, shares, and withdrawals work for vault LPs. This page covers what a depositor (LP) needs to know before, during, and after depositing into a vault. Vault concepts and roles are described in the [Vaults overview](/docs/vaults/vaults). ### Before depositing A vault is a discretionary trading pool. Depositors take on the trading risk taken by the manager, capped at their deposited capital. Pacifica does not vet, audit, or insure third-party vault managers. Treat depositing into a vault the same way you would treat sending capital to any external trader. Before depositing, review: * The manager address, the creator address, and any nickname. The creator can change a small set of trading parameters after creation (see [Managing a Vault → Mutability](/docs/vaults/managing-a-vault#mutability)). * The current symbol whitelist, blacklist, and per-symbol leverage caps. These define what the manager is permitted to trade. * `manager_profit_share` and `deposit_min_duration_ms`. These determine your fees and your minimum lock-up. * `withdraw_window_s` and `withdraw_duration_s` if set. These determine when withdrawals are open. * The current balance, the current LP share count, and the current open positions. These define the NAV at which your shares will be priced. ### How shares are priced on deposit A deposit is converted into LP shares against the vault's net asset value at the moment of deposit. The vault's NAV is the lake account's equity (USDC balance plus unrealized PnL on all open positions, marked to mark price), with the period's PnL first attributed to existing shareholders. ``` NAV_per_share_before_deposit = lp_balance / lp_shares (after accumulated PnL is credited) shares_minted = amount / NAV_per_share_before_deposit = amount * lp_shares / lp_balance ``` If the vault is empty for the LP class (`lp_shares == 0`), shares are minted 1:1 (1 share per 1 USDC). The first step of a deposit is always a "ledger sync" that credits the period's profit or loss to the existing share classes. New shares are then minted at the post-sync NAV, so depositors do not capture or share in PnL that accrued before their deposit. See [Profit & Loss → Ledger sync](/docs/vaults/profit-and-loss#ledger-sync) for the formula. ### Deposit constraints | Constraint | Source | Effect | | ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Minimum deposit | Constant 10 USDC. | Smaller amounts are rejected. | | Deposit cap | Vault config `deposit_cap`. | Total LP balance after the deposit cannot exceed the cap. The manager's own deposits are not counted against the cap. | | Available balance | Standard cross-margin check. | The depositor must have sufficient `available_to_withdraw` to cover the deposit, exactly as for any other USDC outflow. | ### Withdrawing Withdrawals are denominated in shares. The amount returned is your proportional claim on the LP-side balance after the period's PnL has been credited. ``` NAV_per_share_at_withdraw = lp_balance / lp_shares (after ledger sync) amount_withdrawn = shares_redeemed * NAV_per_share_at_withdraw = shares_redeemed * lp_balance / lp_shares ``` A withdrawal is permitted only if all of the following hold: * The depositor holds at least the requested number of shares. * If `deposit_min_duration_ms > 0` is configured, at least that many milliseconds have elapsed since the depositor's most recent deposit. Each new deposit resets the timer for the depositor's entire share balance, not just the new shares. * If `withdraw_window_s` and `withdraw_duration_s` are configured, the current time falls within an open window. The window check is `current_unix_time_s mod withdraw_window_s < withdraw_duration_s`, which means windows are anchored to the Unix epoch (1970-01-01 00:00:00 UTC), not to the vault's creation time. For example, with `withdraw_window_s = 86400` (1 day) and `withdraw_duration_s = 3600` (1 hour), withdrawals are open from 00:00 to 01:00 UTC every day. * The vault has sufficient `available_to_withdraw`. This is the lake account's free balance after subtracting margin reserved for open positions and orders. If the manager has the vault fully deployed in positions, withdrawals may be partially unfilled until the manager closes or de-risks. The redeemed amount is paid in USDC into the depositor's account immediately. The vault's high-water mark is reduced by the same dollar amount paid out, so future performance fees are charged on profit relative to the post-withdrawal balance rather than the pre-withdrawal peak. See [Profit & Loss → High-water mark](/docs/vaults/profit-and-loss#high-water-mark) for the exact behavior under deposits and withdrawals. ### Risks A depositor in a vault can lose up to their entire deposit. There is no Pacifica-funded backstop for vault losses beyond the standard exchange liquidation engine that protects the broader orderbook. Specific exposures to be aware of: * **Trading risk.** The manager's positions can lose money. Losses are taken from the LP balance pro-rata with the manager's balance. Cross-margin liquidations reduce the vault's USDC and may force a withdrawal queue if the lake account's `available_to_withdraw` drops to zero. * **Manager risk.** The manager has discretion within the configured constraints. The creator may also widen those constraints over time (e.g., adding symbols to the whitelist). See [Managing a Vault → Mutability](/docs/vaults/managing-a-vault#mutability). * **Liquidity risk.** Withdrawals require the vault to have free balance. Large drawdowns or fully-deployed positions can delay withdrawals until the manager closes positions or until liquidations run. * **Window risk.** A vault with a withdrawal window restriction is not redeemable outside the window. Plan around the configured cycle. * **Counterparty risk.** A vault deployed by a third party is not Pacifica-operated and is not insured by Pacifica. Treat it accordingly. ### Where to find vault state Vault metadata, configuration, current balances, and share counts are exposed through the standard account and vault endpoints (documented separately under API Documentation). The vault's address is a normal Pacifica account address and can also be inspected on the trading interface like any other account. # Managing a Vault Creating, configuring, and operating a vault on Pacifica. This page covers the manager and creator side of a vault: deploying it, choosing its parameters, and operating it day-to-day. Depositor mechanics are described in [Depositing](/docs/vaults/depositing). ### Creating a vault Vault creation is a single signed call. The creator provides: * An optional `manager` address. If omitted, the vault is created as a "fresh vault" with no manager — any address can later [claim the manager seat](#claiming-a-fresh-vault). * An optional `nickname`, for display on vaults page. Nicknames are unique across all vaults. * An optional [configuration](#configuration) object. If omitted, the default configuration applies (no caps, no fees, no cooldowns, no symbol restrictions). * An optional seed deposit. If provided, the same call also performs a `deposit_to_lake` from the creator into the new vault. A creation fee of 10 USDC is charged to the creator at vault creation. The vault is assigned a freshly-generated address and starts with zero balance, zero shares, and zero positions. A vault may itself be designated as the manager of another vault (a "subvault"). Subvaults are limited to one level of nesting. ### Claiming a fresh vault A fresh vault (created without a manager) can have its manager seat claimed by any address via a signed `claim_lake_manager` call. Claiming requires: * An initial deposit of at least 10 USDC. * If the vault was created with `manager_min_balance_portion` set, the post-claim manager balance ratio must satisfy `manager_balance / (manager_balance + lp_balance) >= manager_min_balance_portion`. Once claimed, the manager seat is permanent for the lifetime of the vault. ### Configuration A vault's behavior is governed by a `LakeConfig`. Some fields are fixed at creation; others can be updated by the creator. All fields are optional. Where a field is `None` the vault behaves as if no constraint of that kind exists. | Field | Mutable? | Description | | ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deposit_cap` | Yes (creator) | Maximum total LP balance accepted by the vault. The manager's own deposits do not count against the cap. `None` = uncapped. | | `whitelist` | Yes (creator) | Symbols the manager is permitted to trade. `None` = all listed symbols allowed. | | `blacklist` | Yes (creator) | Symbols the manager is blocked from trading, applied after the whitelist. A symbol in both lists is blocked. `None` = no blocked symbols. | | `max_leverages` | Yes (creator) | Per-symbol leverage caps for orders placed by the vault. `None` = the symbol's exchange-default max leverage applies. | | `manager_profit_share` | No | Fraction of profits above the high-water mark routed to the manager as a performance fee, in `[0, 1]`. `None` = no fee. See [Profit & Loss](/docs/vaults/profit-and-loss). | | `deposit_min_duration_ms` | No | Minimum time (in milliseconds) a depositor's funds must remain in the vault before they can be withdrawn. Reset on every new deposit by the same depositor. | | `manager_min_balance_portion` | No | Minimum manager-balance ratio required to claim the manager seat and to lift a trading halt. In `[0, 1]`. | | `manager_liquidation_balance_portion` | No | Manager-balance ratio at which the engine halts the vault and liquidates open positions. In `[0, 1]`. Must be strictly less than `manager_min_balance_portion` if both are set. | | `withdraw_window_s` | No | Period of the withdrawal-window cycle in seconds. Must be in `[1 hour, 90 days]`. Set together with `withdraw_duration_s`. | | `withdraw_duration_s` | No | How many seconds out of each `withdraw_window_s` period are open for withdrawals. Must be in `[1 hour, 30 days]` and strictly less than `withdraw_window_s`. | #### Mutability Only the creator can update mutable fields. Updates take effect immediately on the next operation. The non-mutable fields are deliberately fixed at creation: they govern the vault's economics, withdrawal cadence, and risk thresholds. ### Operating the vault The vault is a real Pacifica account. The manager places orders for it through the Pacifica frontend or by using the standard order endpoints, signed by the manager's wallet or by an [agent key](/docs/api-documentation/api/signing/api-agent-keys) bound to the manager's address. All Pacifica trading rules apply unchanged: order types, margin model, mark price, funding, liquidation. See [Trading on Pacifica](/docs/trading-on-pacifica/overview). The manager is also subject to the standard exchange-wide constraints such as rate limits and individual deposit requirements for the vault account itself. ### Manager economics Manager Shares and LP Shares are separate share classes against the same underlying balance and positions. * The manager's deposits and withdrawals follow the same minimum amount and the same `available_to_withdraw` constraints, and the same period-PnL ledger sync as LP deposits and withdrawals. * `deposit_min_duration_ms` and `withdraw_window_s/duration_s` apply to manager withdrawals as well. * When a vault is configured with `manager_min_balance_portion`, the manager must satisfy the threshold to claim the seat and to lift a trading halt. See [Risk Controls → Trading halt and lift](/docs/vaults/risk-controls#trading-halt-and-lift). The manager's earnings come from two sources: 1. The pro-rata return on Manager Shares, identical in form to an LP's return. 2. The performance fee on profits above the high-water mark, set by `manager_profit_share`. The fee is credited to `manager_balance` and accrues to Manager Shares automatically. See [Profit & Loss → Performance fee](/docs/vaults/profit-and-loss#performance-fee). # Profit & Loss How vault PnL is split between LP and Manager Shares. A vault holds a single account balance and a single set of positions. Realized and unrealized PnL accrue to that one account, and the vault then attributes the change to its two share classes (LP and Manager) before any deposit or withdrawal touches the share count. ### Profit attribution If PnL over a period is positive, the manager first takes a performance fee on profits above the vault's high-water mark. The remainder is split pro-rata between LP and Manager balances by their share of the previous period's total balance. ``` fee_eligible_profit = max(current_equity - high_watermark, 0) performance_fee = fee_eligible_profit * manager_profit_share remaining_pnl = period_pnl - performance_fee lp_ratio = lp_balance / (lp_balance + manager_balance) mgr_ratio = manager_balance / (lp_balance + manager_balance) lp_delta = remaining_pnl * lp_ratio mgr_delta = remaining_pnl * mgr_ratio + performance_fee high_watermark = max(high_watermark, current_equity) ``` If `manager_profit_share` is unset it defaults to zero and no performance fee is taken. #### Performance fee The performance fee is charged only on equity above the previous all-time high (the "high-water mark", or HWM). If the vault has been at a loss since its last peak, no performance fee accrues until the prior peak has been recovered. #### High-water mark The HWM moves monotonically upward through trading PnL. It also tracks deposits and withdrawals so that they do not artificially trigger or skip the performance fee: * On a deposit, the HWM increases by the deposit amount. New capital does not retroactively earn or pay performance fees on the prior peak. * On a withdrawal, the HWM is reduced by the gross dollar amount paid out. The profit/loss of the vault is accounted for upon withdrawal with regard to calculating the HWM. The HWM never moves down through trading. Drawdowns must be recovered before the manager earns another performance fee. ### Loss attribution If PnL over a period is negative, the loss is split pro-rata between LP and Manager balances. ``` loss = -period_pnl lp_ratio = lp_balance / (lp_balance + manager_balance) mgr_ratio = manager_balance / (lp_balance + manager_balance) lp_delta = -loss * lp_ratio mgr_delta = -loss * mgr_ratio high_watermark unchanged ``` ### Worked example: profit period A vault with `manager_profit_share = 0.20` starts a period at: ``` lp_balance = 800 manager_balance = 200 lp_shares = 800 manager_shares = 200 high_watermark = 1000 last_checked = 1000 ``` The vault trades to a new equity of `1100`. An LP deposits. ``` period_pnl = 1100 - 1000 = +100 fee_eligible_profit = max(1100 - 1000, 0) = 100 performance_fee = 100 * 0.20 = 20 remaining_pnl = 100 - 20 = 80 lp_ratio = 0.8, mgr_ratio = 0.2 lp_delta = 80 * 0.8 = 64 mgr_delta = 80 * 0.2 + 20 = 36 lp_balance -> 864 (unchanged share count: 800) manager_balance -> 236 (unchanged share count: 200) high_watermark -> 1100 last_checked -> 1100 ``` NAV per LP share rises from 1.00 to 1.08; NAV per Manager Share rises from 1.00 to 1.18 (the manager captured both their pro-rata profit and the 20 USDC performance fee). ### Worked example: loss period A vault starts a period at: ``` lp_balance = 800 manager_balance = 200 high_watermark = 1000 last_checked = 1000 ``` The vault trades to a new equity of `900`. ``` loss = 100 lp_ratio = 0.8, mgr_ratio = 0.2 lp_delta = -80 mgr_delta = -20 lp_balance -> 720 manager_balance -> 180 high_watermark -> 1000 (unchanged) last_checked -> 900 ``` The HWM is unchanged, so the manager will not earn a performance fee until equity recovers above 1000. # Risk Controls Trading constraints, manager balance requirements, halt, and vault liquidation. A vault is a real Pacifica account and is subject to the same liquidation engine as any other account ([Liquidations](/docs/trading-on-pacifica/liquidations)). On top of that, vault-specific controls bound what the manager can do, when the engine forcibly halts trading, and how the manager is required to remain aligned with depositors. This page collects those controls in one place. The economic split during PnL events is described separately in [Profit & Loss](/docs/vaults/profit-and-loss). ### Trading constraints on the manager Every order placed on a vault is checked against the vault's trading configuration in addition to the standard exchange checks. | Constraint | Behavior | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `whitelist` | If set, the order's symbol must be in the whitelist. If unset, all listed symbols are permitted. | | `blacklist` | If set, the order's symbol must not be in the blacklist. The blacklist is applied after the whitelist; a symbol in both lists is blocked. | | `max_leverages[symbol]` | If set, the order's selected leverage on that symbol must not exceed this cap. If unset, the symbol's exchange-default max leverage applies. | | `trading_halt` | If true, all order submissions on the vault are rejected. Set automatically by the liquidation worker; cleared by manager top-up (see below). | Constraint violations are returned as errors at order submission time and do not consume any state. They are checked uniformly for both manual orders and orders placed via an [agent key](/docs/api-documentation/api/signing/api-agent-keys). `whitelist`, `blacklist`, and `max_leverages` can be updated by the creator at any time. Updates take effect on the next order. There is no notice period for depositors. See [Managing a Vault → Mutability](/docs/vaults/managing-a-vault#mutability). ### Manager balance portion The manager's balance portion is the manager's share of the vault's total non-position USDC equity: ``` manager_balance_portion = manager_balance / (manager_balance + lp_balance) ``` Two thresholds in the vault config govern how this ratio is enforced: | Threshold | Configured by | Used at | | ------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | | `manager_min_balance_portion` | Creator (immutable) | Required when claiming the manager seat on a fresh vault. Required to lift a trading halt after liquidation. | | `manager_liquidation_balance_portion` | Creator (immutable) | When the live ratio falls below this threshold, the engine halts trading and liquidates open positions. | `manager_liquidation_balance_portion` must be strictly less than `manager_min_balance_portion` if both are set. The gap between the two acts as a buffer: the manager has room to operate without being one bad tick away from a halt, but is required to top up past the higher threshold to resume trading. If neither portion is configured, the engine does not auto-halt the vault on manager-balance grounds, and the LP is exposed to a manager who can in principle hold zero capital in the vault. # Overview Pacifica's live prediction game. Swim is Pacifica's live prediction game. Watch a market price chart, tap the zones you think the price will move into, and get paid out when you're right. More pairs are coming soon. ### How Swim works The chart sits on top of a live grid of boxes. Each box covers a fixed price range vertically and a fixed time window horizontally, so every cell represents a specific price zone at a specific moment ahead. Tap a box and you're predicting that price will pass through it. If it does, you collect your bet multiplied by that box's payout. ### Trading * Pick a bet size * Tap zones on the grid as the chart moves * Collect `bet × multiplier` any time price enters a zone you tapped ### How Multipliers Work Zone multipliers ladder based on distance in time and price from the current price. The further the zone, the higher the band. These numbers shift constantly as the chart moves. Nothing is locked in until the price actually reaches it. Once you tap a zone, the multiplier shown at that moment is locked in for your bet, regardless of how the grid shifts afterward. ### Balance Swim trades draw directly from your Pacifica trading balance, the same one you use for spot and perps. No separate deposit needed, no extra steps. ### Oracle Swim reads live orderbook prices from leading centralized and decentralized venues, and then aggregates their short term EWMA through a venue-weighted mean. # Connectivity If you’re experiencing issues connecting your wallet to Pacifica - such as a repeated “Connect Wallet” loop, failed transaction signing, or your wallet extension not loading - try the troubleshooting steps below. *** ### Troubleshooting Steps #### 1. Update Wallet Extension Ensure your wallet extension is updated to the latest version and enabled in your browser. * Open your browser’s extension manager. * Confirm wallet is enabled. * Update to the latest version if available. #### 2. Hard Refresh and Clear Cache Perform a hard refresh of your browser: * **Windows:** `Ctrl + Shift + R` * **Mac:** `Cmd + Shift + R` If the issue persists, clear your browser cache and reload the page. #### 3. Disconnect and Reconnect Wallet In wallet: 1. Go to **Settings → Trusted Apps**. 2. Remove Pacifica from the trusted list. 3. Refresh Pacifica and reconnect your wallet. #### 4. Verify Network (Solana Mainnet) Pacifica's deposit/withdrawal operates on Solana. * Ensure your wallet is is connected to **Solana Mainnet**. * If necessary, switch to Devnet or Testnet and then switch back to Mainnet to reset the connection. * Confirm you are not connected to an unsupported cluster. #### 5. Disable Other Wallet Extensions If you have multiple Solana wallet extensions installed, temporarily disable the others and attempt to reconnect using Phantom only. ### Additional Steps If the above does not resolve the issue: * Try opening Pacifica in an incognito/private browser window (with Phantom enabled). * Restart your browser. * Restart your device. If you continue to experience issues, please contact support and include: * Browser and version * Phantom version * Operating system * Screenshot of the error message * Whether you are on desktop or mobile # Recover Assets After Reown to Privy Migration Pacifica has migrated its embedded/social login flow from Reown to Privy. If you originally used **Reown social login** to access Pacifica, your assets are still controlled by the same on-chain wallet. To regain direct control of that wallet, you need to export the wallet's private key from Reown and import it into a wallet you control. This guide is only for **legacy Reown social login users**. If you originally connected a self-custody wallet such as Phantom, Solflare, Backpack, or Ledger, you do not need this recovery flow. > **Important:** Never share your private key with anyone, including Pacifica support. Only export it from Reown's official site, and store it securely offline. ## Official Reown Recovery Page Use Reown's official secure recovery page: ## Video Walkthrough {% embed url="" %} ## What This Process Does The walkthrough shows how to: 1. Sign back into Reown using the same social login you used previously. 2. Export the private key for the wallet created under the old Reown flow. 3. Import that private key into a self-custodial Solana wallet. 4. Use that wallet to access, manage, or withdraw the same assets. ## Step-by-Step Summary 1. Go to Reown's secure recovery page at and sign in with the same social account you previously used on Pacifica. 2. Open the wallet management flow and export the wallet's private key. 3. Store the private key securely before leaving the page. 4. Import that private key into a supported self-custodial Solana wallet. 5. Use the imported wallet to access the same on-chain assets and reconnect to Pacifica if needed. ## Need Help? If you run into issues during this process, contact support and include: * The social login method you originally used * Whether you can still access that same social account * A screenshot of any error or blocked step # Deposit/Withdrawal ### Deposits **Supported asset:** * Please deposit USDC on **Solana** only Deposits sent via any other network or token (e.g., Ethereum, Arbitrum, USDT, SOL) will not be credited. **Minimum deposit:** * 10 USDC Deposits below 10 USDC will not be automatically credited. You may send additional USDC to the same address to reach the minimum. Deposits are usually credited within minutes, but may be delayed due to: * Solana network congestion * RPC instability * Temporary infrastructure load Always verify the transaction on a Solana block explorer before contacting support. *** ### Withdrawals Withdrawals are processed via **USDC on Solana** only. Your Solana wallet must: * Have a valid USDC token account If you encounter an error, ensure there is a **non-zero amount of USDC** already in your wallet to initialize the token account, then retry. Withdrawal delays may occur during periods of Solana network congestion. *** ### Important We highly recommend depositing and withdrawing directly through the Pacifica front-end to avoid errors. Before sending funds: * Double-check the network (Solana) * Confirm the token is USDC * Consider sending a small test transaction for large transfers If issues persist, contact support with your transaction signature (TXID) and relevant details. # Mobile App Account Deletion To request deletion of your Pacifica Mobile account, join the [Pacifica Discord](https://discord.com/invite/dxddmceu4C) and open a support ticket. In your ticket, please include the wallet address associated with your account so the team can identify the correct account. Do not include private keys, seed phrases, passwords, or other sensitive wallet credentials. After your request is reviewed, Pacifica will delete or de-identify account and personal data that is no longer needed to provide the service. Some records may be retained where required for legal, security, anti-fraud, accounting, compliance, dispute-resolution, or regulatory purposes. On-chain wallet activity is public blockchain data and cannot be deleted by Pacifica. For privacy, compliance, or mobile app support questions, open a support ticket in the [Pacifica Discord](https://discord.com/invite/dxddmceu4C). # Trade outcomes # Why was I Liquidated? ### What Happens During Liquidation A liquidation occurs when your position moves against you and your account equity falls below the required **maintenance margin**. When this happens: * Your position is automatically closed by the system * You will see **“Market Liquidation”** in your Trade History * The position size will be reduced to zero (or partially reduced if partial liquidation applies) * Your available balance and margin will update accordingly Liquidations are triggered based on mark price and maintenance margin requirements, not just last traded price. You can read more about how liquidations work on Pacifica here:\ # Why was I liquidated at a different price to what was previously shown? This is most likely a result of cross margining. 1. When you are using cross margin, all your open positions share the same margin pool. 2. The displayed liquidation price is conditional: it typically assumes your other positions don’t change materially. 3. When multiple positions move against you at the same time: losses are accumulated across multiple positions simultaneously. 4. This means shared margin was consumed faster: your total account equity drops quicker than a single-position estimate. 5. Liquidation thresholds adjusted upward in real time: as equity falls, the effective liquidation prices for each position increases. 6. Liquidation triggered at the account level: once total margin fell below requirements, liquidation occurred even if one market hadn’t reached the originally displayed price. How to prevent this: 1. Use isolated margin if you want more stable, predictable liquidation prices per position. 2. Avoid holding multiple correlated positions at high leverage on cross margin. # My TP/SL did not execute properly There are several common cases of TP/SL execution that may be frequently misunderstood. ## # My TP/SL didn’t close my position at the exact price I set. This is normal behavior. A stop loss works very differently from a limit order. A limit order executes only at the specified price or better. A stop order, on the other hand, is triggered when the mark or last traded price reaches the user’s specified trigger level (this can be customized on Pacifica). During periods of volatility, orderbook prices can move past the trigger level before triggering the stop order. This is especially true when mark price is used. This, along with natural orderbook slippage - which can be higher during periods of volatility - causes discrepancies between TP/SL prices and actual execution. This is expected behavior across all exchanges, and it’s extremely rare for a TP/SL order to execute exactly at the trigger price due to normal market movement and liquidity dynamics. # My TP/SL did not close my position as the price kept moving in a single direction. A stop-limit order works in two stages: When the trigger price is reached, it places a limit order at the specified limit price. That limit order will then attempt to execute at that price or better. However, if the market falls through your limit price and doesn’t recover, the limit order may remain unfilled, creating the impression that the stop-limit didn’t work. In reality, it worked as intended - it just couldn’t execute because the market moved past your limit. To guarantee that your position closes once the trigger is hit, consider using a stop-market order instead of a stop-limit order. Stop-market orders prioritize execution, while stop-limits prioritize price.\ \ Especially if using stops to prevent liquidation, we highly recommend using stop market orders to guarantee execution. # My TP/SL was not triggered despite crossing the price level on the chart This is likely because of the mark price being used to trigger stops. Using mark price to trigger stops have the advantage of having exchange-isolated 'wicks' not trigger a user's orders.\ \ If you would like to have TP/SL be triggered using last traded orderbook price, you can change the trigger condition of your stop orders when placing a stop order to "Last traded" ![](https://727612817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO2lcakUmUFILzrKCX989%2Fuploads%2Fs03XSZaFMHNg3M01vc74%2FScreenshot%202026-02-23%20at%204.34.11%E2%80%AFpm.png?alt=media\&token=a15d6b5d-d4c6-4ac8-81bb-a4d4ba706579) # How do TP/SL limit orders work? ## Stop-Loss (SL) and Take-Profit (TP) Limit Orders Stop-Loss and Take-Profit orders are triggered by the **mark/last/mid price**. Once triggered, a limit order is placed to try close off your position. *** ### Long Positions #### Stop-Loss (SL) If you are long and set: * **Trigger price:** $25 * **Limit price:** $25 When the mark price falls below $25, a **limit sell order at $25** will be placed. If the market drops quickly from $26 to $23, your order may rest at $25 without filling. If instead you set: * **Limit price:** $22 The order has a higher probability of filling somewhere between $23 and $22 during a sharp move. Lower limit prices increase fill probability but may result in worse execution. *** #### Take-Profit (TP) If you are long and set: * **Trigger price:** $32 * **Limit price:** $31.50 When the mark price rises above $32, a **limit sell order at $31.50** will be placed. This protects you from selling below $31.50 if the price quickly retraces after triggering. *** ### Short Positions #### Stop-Loss (SL) If you are short and set: * **Trigger price:** $30 * **Limit price:** $30 When the mark price rises above $30, a **limit buy order at $30** will be placed. If the market spikes rapidly from $29 to $33, your order may not fill. If instead you set: * **Limit price:** $34 The order has a higher probability of filling somewhere between $33 and $34 during fast upward moves. Higher limit prices improve fill probability but may result in worse execution. *** #### Take-Profit (TP) If you are short and set: * **Trigger price:** $20 * **Limit price:** $20.50 When the mark price falls below $20, a **limit buy order at $20.50** will be placed. This ensures the order will not fill at a worse price (above $20.50) if the market rebounds after triggering. # Points Program The Pacifica Points program recognizes and rewards users who contribute to Pacifica's success. The Pacifica Points program launched on Thursday, September 4th at 00:00 UTC. Each week: * Snapshots are taken every Thursday at 00:00 UTC * Distributions occur within 24 hours of each snapshot * Weekly allocation: 10,000,000 points distributed weekly among eligible Pacifica users Earn points by engaging in organic trading activities on Pacifica via GUI or API. Self-trading, sybil or any other manipulative activities will not earn points.
### FAQ: #### What is the Pacifica Points formula? The formula is dynamic and opaque by design, updated weekly as usage evolves. #### What activities earn points? Many activities are tracked by our points program, and attribution for different activities may happen immediately or be applied over-time over several distributions. #### Who knows the details of the points program? Very few Pacifica team members. Only Pacifica's community members are eligible to earn points in order to ensure fairness and prevent abuse. #### Do people with multiple accounts have an advantage over me? No. Discrete or costless actions do not yield rewards in isolation. Having 100 accounts provides no advantage over one. #### Do early users have an advantage? Pacifica's points program is structured to balance both early supporters and long-term contributors fairly. #### Can I buy points? No. There was no prior allocation and there is no way to purchase points. They can only be earned by trading, providing feedback, and spreading the word. #### Can I trade points on secondary markets? While Pacifica cannot/will not actively police this, we do not condone any such activity and strongly discourage this for security reasons. # Referral and Affiliate Program Pacifica provides a referral and affiliate system in order for users to be rewarded for inviting their community and friends to trade on the platform. ### Referrals Once you have generated $10,000 in volume, you will be able to generate a referral link on [app.pacifica.fi/referral](https://app.pacifica.fi/referral), and share them with others to use in order to sign into Pacifica as your referee.
Referrers receive 10% of the points generated by their referred users. * Referees will receive a 5% point bonus * Fee and point rewards are automatically credited to the referrer account alongside the weekly points distribution, based on the referred users' trading activity. * There is no application process required, every user can generate their unique referral link directly from their account dashboard after reaching the $10,000 volume threshold. NOTES: Pacifica's referral portal updates once every 15 minutes. If you have recently reached the $10,000 threshold or have recently referred friends, please wait up to 15 minutes before they appear in your portal.\ \ **How do I use a referral code?** After creating a new wallet and joining Pacifica, navigate to the top-right corner and open the referral section. There, you'll be prompted to enter a referral code. By using a referral code during signup, your account will be linked as a referee to the user who generated that code.. **How do I create a referral link?**\ \ At the top part of the referral page ([app.pacifica.fi/referral](https://app.pacifica.fi/referral)), you will see the "Generate Referral Link" button. Once you click it, you will be prompted to enter your preferred referral name. Once you have done that, you will be able to copy and paste the link. This will allow people to join Pacifica as your referral by just clicking it.
**How do I use a referral link?**\ \ When joining Pacifica on a fresh wallet, through a referral link you will be prompted to connect your wallet, and then claim the referral code as shown below. Using a referral link to sign up to Pacifica will attach your account as a referee to the generator of the referral link. The referral will directly use up the amount of codes you have available. In order to claim a referral code you must deposit.
### Affiliates Pacifica Affiliates receive fee share **incentives of up to 40%** from their referees. Spots in the Pacifica Affiliate program are limited, and participation is a selective process based on the Pacifica team's discretion. The fee share an affiliate earns from referrals scales with the total volume their referred users generate, allowing affiliates to unlock higher percentages as they bring more value to the platform. If you believe that you have a large trading community that are interested in trading on Pacifica, please open a ticket at [discord.gg/pacifica](https://discord.gg/pacifica) for additional information. #### Exceptions to Referrals and Affiliate Rewards Referee accounts that become part of Pacifica's market maker program will no longer provide cash reward to their referrers. # Market Maker Program This document provides an overview of the Pacifica Market Making Program. For full details, please reach out to the Pacifica team (see below) ### Program Overview The Pacifica Market Making program exists to ensure a healthy marketplace, benefitting traders with tight spreads and deep liquidity. The program aims to foster a fair and open competitive environment, where Liquidity Providers are able to earn rewards proportional to their relative contributions to these goals. In order to assist in liquidity provisioning, MM program participants enjoy the following: * Zero fees on maker fills * Greatly increased rate-limits * Increased deposit caps ### Eligibility All users of Pacifica Exchange are eligible to participate in the Market Making program, opt-in is required in order to set up reporting channels and apply for zero-maker-fee grace periods while ramping up. To qualify for rewards beyond the initial program launch assessment period, an eligible Market Maker must meet the minimum requirement of X% of the Total MakerScore for the relevant period\ \ This amount will be determined soon, and is subject to change over time based on liquidity conditions on Pacifica. ### Scoring Participants in the Pacifica Market Making program are scored and rewarded based on the following criteria. For full details, please reach out to Pacifica Institutional (see below): * Maker Volume * Pairs Traded * Quote spread and depth * Quote uptime ### Rewards After the Market Maker’s score is calculated for each assessment period, trading rewards for the period can be received in the form of points OR cash, and makers can choose a combination of the two. The USD pool available to be distributed each period is calculated as:\ 12% of total trading fees collected from all market maker counterparties. The Points pool to be distributed each period is 2,000,000 points (1,000,000/week) ### Additional Specs * MM accounts earn points as per the regular points program for all non-maker activity * MM accounts pay regular taker fees based on total trading volume. * MM accounts and subaccounts are ineligible for participation in exchange-wide trading competitions unless otherwise specified. * Weekly reports will be sent summarizing maker performance. * Maker rewards will be sent during points distributions every 14 days. ### Full Details and Application For full Pacifica Market Making Program specs and details, as well as to apply to be part of the program, please reach out to us at [ops@pacifica.fi](mailto:undefined) or open a ticket at [discord.gg/pacifica](https://discord.gg/pacifica) Note: Pacifica monitors all trading activities closely. We do not tolerate market manipulation or abusive trading activities of any kind. If we suspect a participant to be in violation, we reserve the right to modify or deny their rewards entirely. Pacifica reserves the right to modify aspects of the Market Maker Program based on changing market and liquidity conditions.
# Builder Program Pacifica's builder program allows third-party developers (“builders”) to earn fees for orders they send on behalf of the users. These must be **approved by the user** before they can be used on any order. Once approved, the builder may include the code in any supported order creation request. Users can revoke access at any time. Builder codes affect only Pacifica’s order fee logic and are fully verified by the API according to user approval, fee limits, and builder configuration.\ \ We’re setting aside **up to a total of 10,000,000 points** to reward teams building on Pacifica's Builder Program. As of the 12th of March, 2026, the **builder rewards program** has been **extended** by an additional three months. Volume two will run from **March 12th, 2026 to June 12th, 2026.** **Builder Program Rewards** will be distributed based on each team’s contribution to Pacifica’s growth. To ensure fairness and meaningful impact within the ecosystem, an evaluation process will be conducted. Only teams that make significant contributions to Pacifica’s development will be eligible to receive point rewards. ### Step 1: Request User Authorization Request the user to authorize placing orders with your builder code by prompting them to sign an approval request containing your builder code as `builder_code` and the additional fee rate you want to charge as `max_fee_rate`. **Important:** The user's `max_fee_rate` must be greater than or equal to your builder's `fee_rate`. If they set a lower value, orders will be rejected. **Data to be Signed** To approve a builder code, the user signs: ```json { "timestamp": , "expiry_window": 5000, "type": "approve_builder_code", "data": { "builder_code": "YOUR_CODE", "max_fee_rate": "0.001" } } ``` After following the [signing implementation](https://docs.pacifica.fi/api-documentation/api/signing/implementation), compact and sort this payload recursively to generate the signature. **Complete Payload (After Signing)** ``` { "account": "6ETn....", "agent_wallet": null, "signature": "5j1Vy9UqYUF2jKD9r2Lv5AoMWHJuW5a1mqVzEhC9SJL5GqbPkGEQKpW3UZmKXr4UWrHMJ5xHQFMJkZWE8J5VyA", "timestamp": 1748970123456, "expiry_window": 5000, "builder_code": "YOUR_CODE", "max_fee_rate": "0.001" } ``` **Endpoint:** `POST https://api.pacifica.fi/api/v1/account/builder_codes/approve` **Check User Approvals (Optional)** You can query which builder codes a user has approved: **Endpoint:** `GET https://api.pacifica.fi/api/v1/account/builder_codes/approvals?account=6ETn....` **Response:** ``` [ { "builder_code": "YOUR_CODE", "description": "Test Builder Integration", "max_fee_rate": "0.001", "updated_at": 1748970123456 } ] ``` **Revoke Builder Code Authorization (Optional)** Users can revoke authorization at any time: **Data to be Signed** ``` { "timestamp": 1748970123456, "expiry_window": 5000, "type": "revoke_builder_code", "data": { "builder_code": "YOUR_CODE" } } ``` **Complete Payload (After Signing)** ``` { "account": "6ETnufiec2CxVWTS4u5Wiq33Zh5Y3Qm6Pkdpi375fuxP", "agent_wallet": null, "signature": "5j1Vy9UqYUF2jKD9r2Lv5AoMWHJuW5a1mqVzEhC9SJL5GqbPkGEQKpW3UZmKXr4UWrHMJ5xHQFMJkZWE8J5VyA", "timestamp": 1748970123456, "expiry_window": 5000, "builder_code": "YOUR_CODE" } ``` **Endpoint:** `POST https://api.pacifica.fi/api/v1/account/builder_codes/revoke`
### **Step 2: Include Builder Code in Order Creation Requests** All order creation requests may now include your builder code in the `builder_code` parameter. Update the following endpoints: **REST API:** * `POST /api/v1/orders/create_market` * `POST /api/v1/orders/create` * `POST /api/v1/orders/stop/create` * `POST /api/v1/positions/tpsl` **WebSocket:** * `create_market_order` * `create_limit_order` * `create_stop_order` * `set_position_tpsl` **Example: Create Market Order with Builder Code** **Data to be Signed** ``` { "timestamp": 1716200000000, "expiry_window": 30000, "type": "create_market_order", "data": { "symbol": "BTC", "amount": "0.1", "side": "bid", "slippage_percent": "0.5", "reduce_only": false, "client_order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "builder_code": "YOUR_CODE" } } ``` **Complete Payload (After Signing)** ``` { "account": "6ETnufiec2CxVWTS4u5Wiq33Zh5Y3Qm6Pkdpi375fuxP", "agent_wallet": null, "signature": "5j1Vy9UqYUF2jKD9r2Lv5AoMWHJuW5a1mqVzEhC9SJL5GqbPkGEQKpW3UZmKXr4UWrHMJ5xHQFMJkZWE8J5VyA", "timestamp": 1716200000000, "expiry_window": 30000, "symbol": "BTC", "amount": "0.1", "side": "bid", "slippage_percent": "0.5", "reduce_only": false, "client_order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "builder_code": "YOUR_CODE" } ``` **Endpoint:** `POST https://api.pacifica.fi/api/v1/orders/create_market` **Example: Create Limit Order with Builder Code** **Data to be Signed** ``` { "timestamp": 1716200000000, "expiry_window": 30000, "type": "create_order", "data": { "symbol": "BTC", "amount": "0.1", "side": "bid", "tick_level": 1000, "tif": "gtc", "reduce_only": false, "client_order_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "builder_code": "YOUR_CODE" } } ``` **Endpoint:** `POST https://api.pacifica.fi/api/v1/orders/create` **Example: Set Position TP/SL with Builder Code** **Data to be Signed** ``` { "timestamp": 1716200000000, "expiry_window": 30000, "type": "set_position_tpsl", "data": { "symbol": "BTC", "side": "bid", "take_profit": { "stop_price": "55000", "limit_price": "54950", "client_order_id": "e36ac10b-58cc-4372-a567-0e02b2c3d479" }, "stop_loss": { "stop_price": "48000", "limit_price": "47950", "client_order_id": "d25ac10b-58cc-4372-a567-0e02b2c3d479" }, "builder_code": "YOUR_CODE" } } ``` **Complete Payload (After Signing)** ``` { "account": "6ETnufiec2CxVWTS4u5Wiq33Zh5Y3Qm6Pkdpi375fuxP", "agent_wallet": null, "signature": "5j1Vy9UqYUF2jKD9r2Lv5AoMWHJuW5a1mqVzEhC9SJL5GqbPkGEQKpW3UZmKXr4UWrHMJ5xHQFMJkZWE8J5VyA", "timestamp": 1716200000000, "expiry_window": 30000, "symbol": "BTC", "side": "bid", "take_profit": { "stop_price": "55000", "limit_price": "54950", "client_order_id": "e36ac10b-58cc-4372-a567-0e02b2c3d479" }, "stop_loss": { "stop_price": "48000", "limit_price": "47950", "client_order_id": "d25ac10b-58cc-4372-a567-0e02b2c3d479" }, "builder_code": "YOUR_CODE" } ``` **Endpoint:** `POST https://api.pacifica.fi/api/v1/positions/tpsl` **Note:** `builder_code` is provided only at the top level for TP/SL creation, not within individual `take_profit` or `stop_loss` objects.
### Implementation Notes * **Signature Generation:** Follow the standard [signing implementation](https://docs.pacifica.fi/api-documentation/api/signing/implementation) for all requests * **Builder Code Placement:** The `builder_code` must be included in the `data` object when creating the payload to be signed * **Recursive Sorting:** All JSON keys must be recursively sorted alphabetically before creating the compact JSON string * **Timestamps:** All times are in milliseconds * **Expiry Window:** Defaults to 30 seconds (30,000 ms) if not specified * **Backwards Compatibility:** The `builder_code` field is optional on all order creation endpoints * **Validation:** Orders with builder codes will be rejected if: * The builder code doesn't exist * The user hasn't approved the builder code * The user's `max_fee_rate` is less than the builder's `fee_rate` ### Update Builder Code Fee Rate Update the fee rate for your builder code. This endpoint is for builder account owners to change the fee they charge on orders sent with their builder code.\ \ **Request User Authorization (Sign & Send)**\ Builder account owner to sign an update containing the builder code and the new fee rate.
**Data to be Signed** ``` { "timestamp": , "expiry_window": 5000, "type": "update_builder_code_fee_rate", "data": { "builder_code": "YOUR_CODE", "fee_rate": "0.05" } } ``` **Complete Payload (After Signing)** ``` { "account": "6ETn....", "agent_wallet": null, "signature": "5j1V.....", "timestamp": 1748970123456, "expiry_window": 5000, "builder_code": "YOUR_CODE", "fee_rate": "0.05" } ``` **Endpoints:** `POST https://api.pacifica.fi/api/v1/builder/update_fee_rate` ### Referral Code Claim Users can claim a referral code to establish a referral relationship with the code's owner. #### How It Works **Step 1: Request User Authorization** Request the user to authorize claiming a referral code by prompting them to sign an approval request containing the referral code. **Data to be Signed** ``` { "timestamp": , "expiry_window": 5000, "type": "claim_referral_code", "data": { "code": "YOUR_CODE" } } ``` After following the signing implementation, compact and sort this payload recursively to generate the signature. **Complete Payload (After Signing)** ``` { "account": "6ETn....", "agent_wallet": null, "signature": "5jHM.....", "timestamp": 1748970123456, "expiry_window": 5000, "code": "YOUR_CODE" } ``` **Endpoint:** `POST https://api.pacifica.fi/api/v1/referral/user/code/claim` ### **Useful Endpoints** * User trade history via specific builder code: `https://api.pacifica.fi/api/v1/trades/history?account=[WALLET_ADDRESS]&builder_code=[BUILDER_CODE]` * Builder Code Specifications: `https://api.pacifica.fi/api/v1/builder/overview?account=[WALLET_ADDRESS]` * Builder Trade History: `https://api.pacifica.fi/api/v1/builder/trades?builder_code=[BUILDER_CODE]` * Builder Code User Leaderboard: `https://api.pacifica.fi/api/v1/leaderboard/builder_code?builder_code=[BUILDER_CODE]` ### Error Handling **Common Error Codes:** * `403 Unauthorized`: User hasn't approved the builder code or `max_fee_rate` is too low * `404 Not Found`: Builder code doesn't exist * `400 Bad Request`: Invalid builder code format (must be alphanumeric, max 16 characters) ### Full Details and Onboarding For more Pacifica Builder Program specs and details, as well as to onboard to the program, please reach out to us at [ops@pacifica.fi](mailto:undefined), open a support ticket on our [Discord](http://discord.gg/pacifica) or text @PacificaTGPortalBot on telegram. # VIP Program VIP there? VIP here! Want to carry over your trading tier from other exchanges? If you’ve traded on other exchanges, you can verify your past 14 day trading volume and receive the equivalent VIP fee tier on Pacifica for 14 days. How to get started: 1. Open a support ticket on our [Discord](http://discord.gg/pacifica) or text @PacificaTGPortalBot on telegram; let us know you want to verify your volume and join the VIP Program. 2. Our team will guide you through a verification process to prove ownership. 3. Once verified, your external trading volume will be mapped to the appropriate Pacifica VIP tier, and your VIP fee tier will be active for the following 14 days. Notes: * Each Pacifica account can link only one external wallet for this VIP tier match. Enjoy your VIP benefits on Pacifica and thank you for trading with us!
# Educators Program The **Educators Program** has been **discontinued** until further notice. We will review all submissions up to date and will share more details regarding winning submissions soon. Thanks for everyone who has participated!\ \ Winning submissions will be announced on our discord: [discord.gg/pacifica](https://t.co/mJbPQx0UY7)
# Bug Bounty Program Pacifica is committed to maintaining the highest standards of security. We invite security researchers to identify and disclose vulnerabilities in a constructive and responsible manner and help us protect our users, infrastructure, and ecosystem. ## Pacifica Bug Bounty Program Rules 1. Please submit a clear and detailed report with reproducible steps via email to or open a ticket on Pacifica's [Discord](https://discord.gg/pacifica). 2. If we cannot reproduce the issue from your submission, it will not qualify for a reward. 3. Social engineering attacks (e.g., phishing) against Pacifica employees or community members are strictly prohibited. 4. Please make a good faith effort to avoid privacy violations, data loss, service degradation, or interruptions. 5. Actions that negatively impact the availability of Pacifica services (e.g., DoS/DDoS) are not allowed. 6. The bug bounty does not pay-out any attacks that directly disrupt services. **Testnet Guidelines** * If you wish to test asset-related features, please do so on the Pacifica testnet at * For testnet only vulnerabilities not reproducible on mainnet, bounty level will be lowered * Not all testnet features are eligible for the program (newly deployed features known by the team to be unstable, for example) * Reach out to the team at or on [Discord](https://discord.gg/pacifica) for more on using the Pacifica testnet *** ### Bug Bounty Vulnerability Levels
LevelBounty
Critical10,000-25,000 USDC
High2,500-10,000 USDC
Medium500-2,500 USDC
Low500 USDC
**How are the various levels of bugs/vulnerabilities defined?** To ensure consistent triage and fair rewards, vulnerabilities are classified into **Critical, High, Medium, and Low** categories. The following descriptions serve as a guide, and are not exhaustive: #### Critical Vulnerabilities Critical issues directly compromise Pacifica’s **core systems, infrastructure, or smart contracts** in ways that could result in the safety of user deposits or core systems on Pacifica being compromised. #### High-Risk Vulnerabilities High-risk issues compromise system integrity, sensitive data, or critical business logic, but with limited impact relative to Critical Vulnerabilities. #### Medium-Risk Vulnerabilities Medium-risk issues impact user accounts, degrade service, or allow targeted exploitation, but do not put the entire system or core contracts at risk. #### Low-Risk Vulnerabilities Low-risk issues generally require user interaction, have limited impact, or only reveal non-critical information. *** ### Submission Process * Consolidate your findings neatly in writing that includes the following: * A clear description of the bug/issue. * Step-by-step instructions on reproducing the issue on our end. * Proof-of-concept (PoC) or exploit script (if applicable). * Send reports to: (flag any such reports as \[important] or \[urgent]. * Alternatively, reach out to the team on [Discord](http://discord.gg/pacifica) by opening a ticket. * Include impact assessment and suggested remediation steps * Provide screenshots, videos, or other evidence to support your findings if applicable **Important Guidelines:** * If the same vulnerability is reported by multiple researchers, the first complete submission will be rewarded * Submit one vulnerability per report, unless chaining vulnerabilities is necessary to demonstrate real impact. * Multiple vulnerabilities that stem from a single root cause will be treated as one bounty. * Rewards are paid in USDC to the submitter's Pacifica account for responsible disclosure of bugs after assessment by the Pacifica team. * All research must be conducted ethically and responsibly in accordance to the rules of the Pacifica bug bounty program. *** ### Prohibited Activity **The following activities are strictly prohibited, and will result in a report becoming ineligible for the bug bounty and/or further investigation and legal action.** * Direct testing on the Pacifica mainnet in a manner that results in/may result in service disruption or data loss. All attempts must be done on Pacifica Testnet. * Any phishing, social engineering, or physical security attacks. * Denial-of-Service (DoS) or large-scale DDoS attacks. * Testing third-party apps (SSO providers, wallets, browser extensions) outside Pacifica's control. * Violating user privacy or accessing accounts belonging to others without consent. * Public disclosure of vulnerabilities prior to their resolution without consent or authorization. * Threats, ransom demands, or publishing sensitive data without consent. * Exploiting vulnerabilities for personal financial gain beyond bug bounty rewards. *** ### Eligibility * Reports must be submitted to Pacifica team directly via email or Discord. Others are not accepted. * You must comply with KYC verification to be eligible for any bug bounty rewards and to be able to receive USDC payouts on Pacifica. * You must maintain strict confidentiality about discovered vulnerabilities until authorized disclosure. #### The following are NOT eligible for the bug bounty program: * UI/UX bugs without security implications. * Reports without sufficient detail, reproducible steps, or PoC. * Vulnerabilities requiring highly improbable user actions, unrealistic market conditions or social engineering. * Issues in outdated browsers, plugins, or operating systems not supported by Pacifica. * Vulnerabilities requiring physical access to user devices. * Bugs in third-party libraries or services that don't create direct risk to Pacifica users. * Non-security related bugs such as cosmetic issues or minor functional problems. * Theoretical vulnerabilities without demonstrable security impact. *** All submissions must meet program requirements to be eligible for rewards. Pacifica reserves full discretion in classifying reported issues and determining payout amounts. By submitting a report, you acknowledge that it becomes the property of Pacifica, and we may use, modify, or disclose the information as necessary to improve the security of our platform. In return, Pacifica is committed to treating researchers with respect and fairness. We will investigate all valid reports promptly, provide clear reasoning behind our classifications, and reward based on the severity of the issue. Most importantly, we will pursue legal action against those who do not conduct research in good faith. # Affiliate Program Pacifica provides an affiliate system in order for community owners and KOLs to be rewarded for inviting their community and friends to trade on the platform. Pacifica Affiliates receive fee share **incentives of up to 40%** from their referees. Spots in the Pacifica Affiliate program are limited, and participation is a selective process based on the Pacifica team's discretion.\ \ If you believe that you have a large trading community that are interested in trading on Pacifica, please open a ticket at [discord.gg/pacifica](https://discord.gg/pacifica) for additional information. # Outdated/To be restructured # Order Rules & Constraints Pacifica applies specific rules to maintain orderly and fair trading conditions. ### Self-Trade Prevention Pacifica prevents self-trading by automatically canceling resting orders that match against newly placed aggressive orders from the same account. This ensures fair and efficient market conditions. ### Maximum Order Size Your maximum order size is dynamically determined based on your available margin, leverage, and current positions. The calculation is: ``` max_order_size = order_from_balance + order_from_opposite ``` * order\_from\_balance: Determined by your available margin and leverage. * order\_from\_opposite: Calculated based on existing opposite positions and outstanding orders, enabling you to close positions without exceeding margin limits. ### Example If you have an account balance of $10,000 with 10x leverage and BTC price at $100,000, your maximum long order size initially would be: ``` order_from_balance = ($10,000 * 10) / $100,000 = 1 BTC ``` With an open 1 BTC long position and fully utilized margin, you cannot place additional buy orders but can place sell orders to reduce your position: ``` order_from_balance = 1 BTC order_from_opposite = 1 BTC (existing long position) - 0 (existing short orders) - 0 (existing long orders) = 1 BTC max_order_size = 1 BTC + 1 BTC = 2 BTC ``` Thus, you can place sell orders up to 2 BTC in size to close and/or reverse your position. # Getting Started # Deposit Flow Before trading, you’ll need a compatible crypto wallet with a Solana address connected to Pacifica, and USDC collateral to fund your trades. Pacifica supports multiple wallet types, including: * Phantom, Solflare, Backpack, Ledger (via browser extension), and other WalletConnect-compatible wallets If you don’t yet have a wallet, you can quickly create one directly on Pacifica: * Sign up using your Email, Google, or X account. * For a self-custody wallet, choose from available options on WalletGuide. ANIMATED GIF HERE: (Pacifica’s wallet creation options: email, Google, X, WalletGuide link) Depositing funds into your Pacifica account is a secure, streamlined process that ensures your account is properly collateralized, enabling you to open and manage positions effectively. Follow these steps to initiate and complete a deposit: {% stepper %} {% step %} #### Install Phantom * Go to [phantom.com](https://phantom.com/), and install the extension (Chrome/Brave) or mobile app. ANIMATED GIF HERE: (Phantom installation page) {% endstep %} {% step %} #### Fund Phantom Wallet * Send USDC or SOL from your exchange or existing wallet into Phantom. * Confirm funds arrival within Phantom. ANIMATED GIF HERE: (Phantom wallet balance screen) {% endstep %} {% step %} #### Connect to Pacifica * Visit pacifica.fi * Click “Connect Wallet”, choose Phantom, and approve the connection. ANIMATED GIF HERE: (Pacifica’s Connect Wallet prompt with Phantom selected) {% endstep %} {% step %} #### Deposit Collateral * Navigate to the "Deposit" section on Pacifica * Choose the collateral amount and confirm the transaction. ANIMATED GIF HERE: (Pacifica collateral deposit page) {% endstep %} {% step %} #### Verify Your Balance * Check your Portfolio or Balances section to ensure your deposited collateral is reflected correctly. {% endstep %} {% endstepper %} With your wallet connected and collateral deposited, you’re now ready to trade. For further details or troubleshooting during the deposit process, please refer to our [FAQ](/docs/other/faqs) or [contact our team](/docs/other/contact-us). # Withdrawal Flow Withdrawing your funds from Pacifica is a secure, two-step process that ensures your open positions remain adequately collateralized while allowing you to retrieve available funds. Follow these steps to initiate and complete a withdrawal: {% stepper %} {% step %} #### Connect to Pacifica * Visit pacifica.fi * Click “Connect Wallet”, choose Phantom, and approve the connection. {% endstep %} {% step %} #### Specify Withdrawal Amount * Enter the amount you wish to withdraw. * **Minimum Withdrawal:** $1 (withdrawals below this amount will not be processed). * Verify that you have sufficient free collateral available—withdrawals cannot compromise the collateral requirements for any open positions. {% endstep %} {% step %} #### Review Fees & Confirm * Upon confirmation, your account balance is immediately adjusted, and the requested amount is moved into a pending state. * This pending stage ensures that your open positions remain fully collateralized while your withdrawal is being processed. * Once the transaction is confirmed, the pending entry is removed, and your withdrawal is finalized. Your withdrawn funds will then appear in your connected wallet. {% endstep %} {% step %} #### Verify Receipt * After the transaction is complete, check your wallet to confirm that the funds have been successfully transferred. * If you encounter any issues or delays, consult the troubleshooting section in our [FAQ](/docs/other/faqs) or [contact us](/docs/other/contact-us). {% endstep %} {% endstepper %} *** Following these steps will ensure your withdrawal is processed securely and efficiently, keeping your account and open positions safe while returning your collateral back to your wallet. # About Pacifica # API Welcome to Pacifica's API documentation. We offer complete REST and Websocket APIs to suit your trading needs.\ \ The documentation includes clear descriptions, parameter requirements, example responses, and code snippets to help developers quickly implement these endpoints in their applications.\ \ You can also use the API via the Pacifica Python SDK: \ \ For any feedback, suggestions, and additional help with integration into Pacifica's API, please let us know in our [discord API channel](https://discord.com/channels/1325864651816435822/1378723526957334548)!\
# REST API All example API calls use the Pacifica Mainnet URL, but you can make the same requests against Testnet using the the Pacifica Testnet url. Mainnet REST endpoint URL: \ Testnet REST endpoint URL: Requests and responses use JSON. # Markets This sections covers details for interacting with all perpetual futures markets listed on Pacifica. # Get market info This endpoint allows users to get exchange information, including market specifications for all available trading pairs. ``` GET /api/v1/info ``` #### Response * Status 200: Success ```json { "success": true, "data": [ { "symbol": "ETH", "tick_size": "0.1", "min_tick": "0", "max_tick": "1000000", "lot_size": "0.0001", "max_leverage": 50, "isolated_only": false, "min_order_size": "10", "max_order_size": "5000000", "funding_rate": "0.0000125", "next_funding_rate": "0.0000125", "created_at": 1748881333944 }, { "symbol": "BTC", "tick_size": "1", "min_tick": "0", "max_tick": "1000000", "lot_size": "0.00001", "max_leverage": 50, "isolated_only": false, "min_order_size": "10", "max_order_size": "5000000", "funding_rate": "0.0000125", "next_funding_rate": "0.0000125", "created_at": 1748881333944 }, .... ], "error": null, "code": null } ```
FieldTypeDescription
"symbol"stringTrading pair symbol
"tick_size"decimal stringTick size. All prices are denominated as a multiple of this.
"min_tick"decimal stringMinimum tick. API submitted price cannot be below this value
"max_tick"decimal stringMaximum tick. API submitted price cannot be above this value
"lot_size"decimal stringLot size. All order sizes (token denominated) are denominated as a multiple of this.
"max_leverage"integerMaximum leverage allowed on this symbol when opening positions
"isolated_only"booleanIf the market is set to only allow isolated positions
"min_order_size"decimal stringMinimum order size (denominated in USD)
"max_order_size"decimal stringMaximum order size (denominated in USD)
"funding_rate"decimal stringFunding rate paid in the past funding epoch (hour)
"next_funding_rate"decimal stringEstimated funding rate to be paid in the next funding epoch (hour)
"created_at"ISO 8601 stringTimestamp when the market was listed on Pacifica. Markets are returned oldest first.
* Status 500: Internal server error #### Code Example (Python) ```json import requests response = requests.get( "/api/v1/info", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get prices This endpoint allows users to get price information for all symbols, including mark prices, funding rates, and market statistics. ``` GET /api/v1/info/prices ``` #### Response * Status 200: Success ```json { "success": true, "data": [ { "funding": "0.00010529", "mark": "1.084819", "mid": "1.08615", "next_funding": "0.00011096", "open_interest": "3634796", "oracle": "1.084524", "symbol": "XPL", "timestamp": 1759222967974, "volume_24h": "20896698.0672", "yesterday_price": "1.3412" } ], "error": null, "code": null } ```
FieldTypeDescription
"funding"decimal stringfunding rate paid in the past funding epoch (hour)
"mark"decimal stringMark price, as defined above
"mid"decimal stringMid price, defined as the average of the best bid and best ask price
"next_funding"decimal stringestimated funding rate to be paid in the next funding epoch (hour)
"open_interest"decimal stringThe current open interest on this symbol (in USD)
"oracle"decimal stringOracle price, as defined above
"symbol"stringTrading pair symbol
"timestamp"integerTimestamp in Milliseconds
"volume_24h"booleanVolume (USD) of this market in the past 24 hours
"yesterday_price"decimal stringOracle price of this market 24 hours ago (USD)
* Status 404: No prices data available * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/info/prices", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get candle data This endpoint allows users to get historical price candles for a specific market and time interval. ``` /api/v1/kline ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"symbol"stringrequiredTrading pair symbolBTC
"interval"stringrequiredCandlestick interval
Valid values: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d		1m
"start_time"integerrequiredStart time in milliseconds1716200000000
"end_time"integeroptionalEnd time in milliseconds, defaults to current time if not provided1742243220000
``` /api/v1/kline?symbol=BTC&interval=1m&start_time=1742243160000&end_time=1742243220000 ``` #### Response * Status 200: Successfully retrieved candle data ```json { "success": true, "data": [ { "t": 1748954160000, "T": 1748954220000, "s": "BTC", "i": "1m", "o": "105376", "c": "105376", "h": "105376", "l": "105376", "v": "0.00022", "n": 2 } ], "error": null, "code": null } ``` | Field | Type | Description | | ----- | -------------- | ------------------------------------------------- | | `'t'` | number | Candle start time | | `'T'` | number | Candle end time | | `'s'` | string | Symbol | | `'i'` | string | Time interval of candles | | `'o'` | decimal string | Open price | | `'c'` | decimal string | Close price | | `'h'` | decimal string | High price | | `'l'` | decimal string | Low price | | `'v'` | decimal string | Volume | | `'n'` | number | Number of trades on Pacifica for specified symbol | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/kline?symbol=BTC&interval=1m&start_time=1742243160000&end_time=1742243220000", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get mark price candle data This endpoint allows users to get historical mark price candles for a specific market and time interval. ``` /api/v1/kline/mark ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"symbol"stringrequiredTrading pair symbolBTC
"interval"stringrequiredCandlestick interval
Valid values: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d		1m
"start_time"integerrequiredStart time in milliseconds1716200000000
"end_time"integeroptionalEnd time in milliseconds, defaults to current time if not provided1742243220000
``` /api/v1/kline/mark?symbol=BTC&interval=1m&start_time=1742243160000&end_time=1742243220000 ``` #### Response * Status 200: Successfully retrieved mark price candle data ```json { "success": true, "data": [ { "t": 1764126720000, "T": 1764126780000, "s": "BTC", "i": "1m", "o": "87701", "c": "87687.303362", "h": "87739", "l": "87687.303362", "v": "0.84106", "n": 62 }, { "t": 1764126780000, "T": 1764126840000, "s": "BTC", "i": "1m", "o": "87684.118667", "c": "87654", "h": "87684.118667", "l": "87645", "v": "4.5997", "n": 91 } ], "error": null, "code": null } ``` | Field | Type | Description | | ----- | -------------- | ----------------------------------------------- | | `'t'` | number | Candle start time | | `'T'` | number | Candle end time | | `'s'` | string | Symbol | | `'i'` | string | Time interval of candles | | `'o'` | decimal string | Open price | | `'c'` | decimal string | Close price | | `'h'` | decimal string | High price | | `'l'` | decimal string | Low price | | `'v'` | decimal string | Volume (always `"0"`) | | `'n'` | number | Number of trades on Pacifica in candle duration | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/kline/mark?symbol=BTC&interval=1m&start_time=1742243160000&end_time=1742243220000", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get orderbook This endpoint allows users to retrieve the current orderbook (bid/ask levels) for a specified trading symbol. ``` /api/v1/book ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"symbol"stringrequiredTrading pair symbolBTC
"agg_level"integernoAggregation level for price grouping. Defaults to 11
``` api/v1/book?symbol=BTC ``` #### Response * Status 200: Successfully retrieved book data ```json { "success": true, "data": { "s": "BTC", "l": [ [ { "p": "106504", "a": "0.26203", "n": 1 }, { "p": "106498", "a": "0.29281", "n": 1 } ], [ { "p": "106559", "a": "0.26802", "n": 1 }, { "p": "106564", "a": "0.3002", "n": 1 }, ] ], "t": 1751370536325 }, "error": null, "code": null } ``` | Field | Type | Description | | ----- | -------------- | -------------------------------------------------------------------------------------------------------- | | `'s'` | string | Symbol | | `'l'` | array | Two-dimensional array containing bids (index 0) and asks (index 1). Each index contains up to 10 levels. | | `'t'` | string | Response timestamp in milliseconds | | `'p'` | decimal string | Price level | | `'a'` | decimal string | Total amount at price level | | `'n'` | integer | Number of orders at level | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "api.pacifica.fi/api/v1/book?symbol=BTC", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get recent trades This endpoint allows users to get recent trades for a specific market. ``` GET /api/v1/trades ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"symbol"stringrequiredTrading pair symbolBTC
``` /api/v1/trades?symbol=BTC ``` #### Response * Status 200: Successfully retrieved recent trades ```json { "success": true, "data": [ { "event_type": "fulfill_taker", "price": "104721", "amount": "0.0001", "side": "close_long", "cause": "normal", "created_at": 1765006315306 } ], "error": null, "code": null, "last_order_id": 1557404170 } ``` | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'event_type'` | string |

"fulfill\_taker" if maker
"fulfill\_maker" if taker

| | `'price'` | decimal string | Price in USD at which trade event has occurred | | `'amount'` | decimal string | Amount in token denomination for which the trade has occurred for. | | `'side'` | string |

"open\_long"
"open\_short"
"close\_long"
"close\_short"

| | `'cause'` | string |

"normal"
regular user-initiated trading
"market\_liquidation" position was liquidated due to insufficient margin
"backstop\_liquidation" position was liquidated by backstop mechanism
"settlement"
position was closed due to Auto-Deleveraging (ADL) or other settlement

| | `'created_at'` | integer | Timestamp in milliseconds of trade event | | `'last_order_id'` | integer | Exchange-wide nonce. Used to reliably determine exchange event ordering. Sequential and not subject to clock drift. | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/trades?symbol=BTC", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get historical funding This endpoint retrieves the historical funding for a particular symbol ``` GET /api/v1/funding_rate/history ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"symbol"stringrequiredMarket symbol to queryBTC
"limit"integeroptionalNumber of records to show (default 100, max 4000)20
"cursor"stringoptionalCursor pagination to access records. Default to none1115hVka
``` /api/v1/funding_rate/history?symbol=BTC&limit=20&cursor=11115hVka ``` #### Response * Status 200: Successfully retrieved funding history ```json { "success": true, "data": [ { "oracle_price": "117170.410304", "bid_impact_price": "117126", "ask_impact_price": "117142", "funding_rate": "0.0000125", "next_funding_rate": "0.0000125", "created_at": 1753806934249 }, ... ], "next_cursor": "11114Lz77", "has_more": true } ``` | Field | Type | Description | | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ | | `'oracle_price'` | decimal string | Oracle price used for [funding rate calculation](https://docs.pacifica.fi/trading-on-pacifica/funding-rates) | | `'bid_impact_price'` | decimal string | Bid impact price at time of calculation (see funding rate docs) | | `'ask_impact_price'` | decimal string | Ask impact price at time of calculation (see funding rate docs) | | `'funding_rate'` | decimal string | Last settled funding rate | | `'next_funding_rate'` | decimal string | Predicted funding rate for next settlement | | `'created_at'` | integer | Timestamp in milliseconds | | `'next_cursor'` | string | Next cursor for pagination | | `'has_more'` | boolean | True if there exists a `'next_cursor'` | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/funding_rate/history?symbol=BTC", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get fee levels This endpoint returns all fee level tiers and their corresponding maker and taker fee rates. ``` GET /api/v1/info/fees ``` #### Response * Status 200: Success ```json { "success": true, "data": [ { "level": 0, "maker_fee_rate": "0.00020", "taker_fee_rate": "0.00050" }, { "level": 1, "maker_fee_rate": "0.00015", "taker_fee_rate": "0.00040" } ], "error": null, "code": null } ```
FieldTypeDescription
"level"integerFee tier level
"maker_fee_rate"decimal stringMaker fee rate for this tier
"taker_fee_rate"decimal stringTaker fee rate for this tier
* Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/info/fees", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get loan pool This endpoint returns the current state of the loan pool including utilization, borrow and lend rates. ``` GET /api/v1/loan_pool ``` #### Response * Status 200: Success ```json { "success": true, "data": { "total_borrowed": "500000.000000", "total_borrowable": "2000000.000000", "utilization": "0.25", "borrow_rate_apr": "0.08", "borrow_rate_apy": "0.0833", "lend_rate_apr": "0.06", "lend_rate_apy": "0.0618", "utilization_max": "0.85", "auto_lender_entry_threshold": "1000.000000", "last_interest_accrual_at": 1716200000000, "last_interest_payout_at": 1716200000000, "updated_at": 1716200000000 }, "error": null, "code": null } ```
FieldTypeDescription
"total_borrowed"decimal stringTotal amount currently borrowed from the pool
"total_borrowable"decimal stringTotal amount available to borrow
"utilization"decimal stringPool utilization ratio (borrowed / total)
"borrow_rate_apr"decimal stringCurrent annualized borrow rate
"borrow_rate_apy"decimal stringCurrent compounded annual borrow rate
"lend_rate_apr"decimal stringCurrent annualized lending rate
"lend_rate_apy"decimal stringCurrent compounded annual lending rate
"utilization_max"decimal stringMaximum utilization cap for the pool
"auto_lender_entry_threshold"decimal stringMinimum balance threshold to be included in auto-lending
"last_interest_accrual_at"integer or nullTimestamp of last interest accrual (ms). null if never accrued
"last_interest_payout_at"integer or nullTimestamp of last interest payout (ms). null if never paid out
"updated_at"integerTimestamp of last update (ms)
* Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/loan_pool", headers={"Accept": "*/*"}, ) data = response.json() ``` # Account This sections covers details for interacting with user accounts on Pacifica. # Get account info This endpoint allows users to get all high-level account info such as balance, fee level, equity, etc. ``` GET /api/v1/account ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredAccount address42trU9A5...
``` /api/v1/account?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved account information ```json { "success": true, "data": { "balance": "2000.000000", "fee_level": 0, "maker_fee": "0.00015", "taker_fee": "0.0004", "account_equity": "2150.250000", "available_to_spend": "1800.750000", "available_to_withdraw": "1500.850000", "pending_balance": "0.000000", "pending_interest": "0.000000", "spot_collateral": "0.000000", "cross_account_equity": "2100.500000", "spot_market_value": "250.000000", "total_margin_used": "349.500000", "cross_mmr": "420.690000", "positions_count": 2, "orders_count": 3, "stop_orders_count": 1, "updated_at": 1716200000000, "spot_balances": [ { "symbol": "SOL", "amount": "1.50000000", "available_to_withdraw": "1.00000000", "pending_balance": "0.50000000", "daily_withdraw_amount_usd": "250.000000", "effective_daily_deposit_limit_usd": "50000.000000", "effective_daily_withdraw_limit_usd": "250000.000000" } ] }, "error": null, "code": null } ``` | Field | Type | Description | | ------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | | `'balance'` | decimal string | Current account balance, defined as amount of USD in account before settlement | | `'fee_level'` | integer | Current fee tier of account, determined by trading volume | | `'maker_fee'` | decimal string | Current maker fee rate of account, determined by trading volume | | `'taker_fee'` | decimal string | Current taker fee rate of account, determined by trading volume | | `'account_equity'` | decimal string | Account balance + unrealized PnL + isolated margin + raw spot market value | | `'available_to_spend'` | decimal string | Amount of account equity that is available to used to margin for open positions and orders | | `'available_to_withdraw'` | decimal string | Amount that is available to withdraw out from the exchange | | `'pending_balance'` | decimal string | Amount of account balance in pending status (deposit request is successful, waiting on confirmation) | | `'total_margin_used'` | decimal string | Amount of account equity currently being used to margin for open positions and orders | | `'cross_mmr'` | decimal string | The maintenance margin required under the cross mode | | `'positions_count'` | integer | Number of open positions (isolated and cross) | | `'orders_count'` | integer | Number of open orders across all markets (excludes stop orders) | | `'stop_orders_count'` | integer | Number of open stop orders across markets | | `'pending_interest'` | decimal string | Accrued loan interest not yet repaid | | `'spot_collateral'` | decimal string | Total USD value of spot assets used as collateral for unified margin | | `'cross_account_equity'` | decimal string or null | Cross-margin equity after applying unified-margin collateral rules. `null` if not applicable | | `'spot_market_value'` | decimal string | Raw marked-to-market value of positive spot balances before collateral haircuts | | `'spot_balances'` | array | List of spot asset balances held by the account (see below) | | `'updated_at'` | integer | Timestamp in milliseconds of last account info update | **Spot Balance Fields** | Field | Type | Description | | -------------------------------------- | -------------- | ----------------------------------- | | `'symbol'` | string | Spot asset symbol | | `'amount'` | decimal string | Total amount of the spot asset held | | `'available_to_withdraw'` | decimal string | Amount available to withdraw | | `'pending_balance'` | decimal string | Amount pending confirmation | | `'daily_withdraw_amount_usd'` | decimal string | USD value of withdrawals made today | | `'effective_daily_deposit_limit_usd'` | decimal string | Daily deposit limit in USD | | `'effective_daily_withdraw_limit_usd'` | decimal string | Daily withdrawal limit in USD | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/account?account=42trU9A5...", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get account settings This endpoint allows users to get account margin and leverage settings (if they are not at default values) ``` GET /api/v1/account/settings ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredAccount address42trU9A5...
``` /api/v1/account/settings?account=42trU9A5... ``` #### Response NOTE: Upon account creation, all markets have margin settings default to cross margin and leverage default to max. When querying this endpoint, all markets with default margin and leverage settings on this account will return blank. * Status 200: Successfully retrieved account settings ```json { "success": true, "data": { "auto_lend_disabled": null, "margin_settings": [ { "symbol": "WLFI", "isolated": false, "leverage": 5, "created_at": 1758085929703, "updated_at": 1758086074002 } ], "spot_settings": [ { "symbol": "SOL", "unified_margin_excluded": false } ], "error": null, "code": null } } ```
FieldTypeDescription
"auto_lend_disabled"boolean or nullWhether automatic lending is disabled for this account. null means default (enabled)
"spot_settings"arrayPer-asset spot settings for unified margin (see below)
"symbol"stringTrading pair symbol
"isolated"booleanIf the account is set to isolated margining for this symbol
"leverage"integerCurrent leverage set by the user (default to max)
"created_at"integerTimestamp in milliseconds when these settings were adjusted from their default
"updated_at"integerTimestamp in milliseconds when these settings were last updated
**Spot Settings Fields** | Field | Type | Description | | --------------------------- | ------- | ---------------------------------------------------------------------------------- | | `"symbol"` | string | Spot asset symbol | | `"unified_margin_excluded"` | boolean | If `true`, this spot asset is excluded from unified margin collateral calculations | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/account/settings?account=42trU9A5...", headers={"Accept": "*/*"}, ) data = response.json() ``` # Update leverage This endpoint allows users to change their account leverage for a specific trading pair. For open positions, users can only increase the leverage setting. ``` POST /api/v1/account/leverage ``` #### Operation Type (for signing) | Header Field | Type | Content | | ------------ | ------ | ------------------- | | `"type"` | string | `"update_leverage"` | Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"symbol"stringrequiredTrading pair symbolBTC
"leverage"integerrequiredNew leverage value10
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"expiry_window"integeroptionalSignature expiry in milliseconds30000
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"signature"stringrequiredCryptographic signature5j1Vy9Uq...
```json { "account": "42trU9A5...", "symbol": "BTC", "leverage": 10, "timestamp": 1716200000000, "expiry_window": 30000, "agent_wallet": "69trU9A5...", "signature": "5j1Vy9UqY..." } ``` #### Response * Status 200: Leverage updated successfully ```json { "success": true } ``` * Status 400: Invalid request parameters ```json { "error": "Invalid leverage", "code": 400 } ``` * Status 500: Internal server error #### Code Example (Python) ```python import requests payload = { "account": "42trU9A5...", "signature": "5j1Vy9Uq...", "timestamp": 1716200000000, "symbol": "BTC", "leverage": 10 } response = requests.post( "/api/v1/account/leverage", json=payload, headers={"Content-Type": "application/json"} ) data = response.json() ``` # Update margin mode This endpoint allows users to switch between isolated and cross margin modes for a specific trading pair. For open positions, users cannot change the margin mode. ``` POST /api/v1/account/margin ``` #### Operation Type (for signing) | Header Field | Type | Content | | ------------ | ------ | ---------------------- | | "type" | string | `"update_margin_mode"` | #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"symbol"stringrequiredTrading pair symbolBTC
"is_isolated"booleanrequiredMargin mode (true for isolated, false for cross)false
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"expiry_window"integeroptionalSignature expiry in milliseconds30000
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"signature"stringrequiredCryptographic signature5j1Vy9Uq...
```json { "account": "42trU9A5...", "symbol": "BTC", "is_isolated": false, "timestamp": 1716200000000, "expiry_window": 30000, "agent_wallet": "69trU9A5...", "signature": "5j1Vy9Uq..." } ``` #### Response * Status 200: Margin mode updated successfully ```json { "success": true } ``` * Status 400: Invalid request parameters ```json { "error": "Invalid margin mode", "code": 400 } ``` * Status 500: Internal server error #### Code Example (Python) ```python import requests payload = { "account": "42trU9A5...", "signature": "5j1Vy9Uq", "timestamp": 1716200000000, "symbol": "BTC", "is_isolated": false } response = requests.post( "/api/v1/account/margin", json=payload, headers={"Content-Type": "application/json"} ) data = response.json() ``` # Get positions This endpoint allows users to get current positions. ``` GET /api/v1/positions ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredConnected wallet address42trU9A5...
``` /api/v1/positions?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved account information ```json { "success": true, "data": [ { "symbol": "AAVE", "side": "ask", "amount": "223.72", "entry_price": "279.283134", "margin": "0", // only shown for isolated margin "funding": "13.159593", "isolated": false, "liquidation_price": null, "created_at": 1754928414996, "updated_at": 1759223365538 } ], "error": null, "code": null, "last_order_id": 1557431179 } ```
FieldTypeDescription
"symbol"stringTrading pair symbol
"side"stringPosition side: bid (long) or ask (short)
"amount"decimal stringPosition size in the asset's base unit
"entry_price"decimal stringEntry price of the position. Takes VWAP if position was opened by multiple trades executed at different prices.
"margin"decimal stringAmount of margin allocated to an isolated position (only shown when isolated)
"funding"decimal stringFunding paid by this position since open
"isolated"booleanIf the position is opened in isolated margin mode
"liquidation_price"decimal string or nullEstimated liquidation price for the position. null if not applicable
"created_at"integerTimestamp in milliseconds when the position was opened
"updated_at"integerTimestamp in milliseconds when these settings were last updated
"last_order_id"integerExchange-wide nonce. Used to reliably determine exchange event ordering. Sequential and not subject to clock drift.
* Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/positions?account=42trU9A5...", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get trade history This endpoint allows users to get trade history ``` GET /api/v1/trades/history ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"symbol"stringoptionalMarket symbol to filter byBTC
"start_time"integeroptionalStart time in milliseconds1625097600000
"end_time"integeroptionalEnd time in milliseconds1759215599188
"limit"integeroptionalMaximum number of records to return, defaults to 100100
"cursor"integeroptionalCursor pagination to access records. Default to none1115hVka
``` /api/v1/positions/history?account=42trU9A5...&start_time=1625097600000&end_time=1759215599188 ``` #### Response * Status 200: Successfully retrieved portfolio position history ```json { "success": true, "data": [ { "history_id": 19329801, "order_id": 315293920, "client_order_id": "acf...", "symbol": "LDO", "amount": "0.1", "price": "1.1904", "entry_price": "1.176247", "fee": "0", "pnl": "-0.001415", "event_type": "fulfill_maker", "side": "close_short", "created_at": 1759215599188, "cause": "normal" }, ... ], "next_cursor": "11111Z5RK", "has_more": true } ```
FieldTypeDescription
"history_id"integerHistory id of trade
"order_id"integerOrder id of order that resulted in the trade
"client_order_id"UUIDCLOID of order that resulted in the trade
"symbol"stringTrading pair symbol
"amount"decimal stringAmount (in token denomination) of the trade event
"price"decimal stringCurrent price of the specified symbol
"entry_price"decimal stringPrice at which the trade event was executed
"fee"decimal stringFee paid by the trade event
"pnl"decimal stringPnL generated by the trade event
"event_type"string"fulfill_taker" if taker
"fulfill_maker" if maker
"side"string"open_long"
"open_short"
"close_long"
"close_short"
"created_at"integerTimestamp in milliseconds when the trade event occurred
"cause"string"normal"
regular user-initiated trading
"market_liquidation" position was liquidated due to insufficient margin
"backstop_liquidation" position was liquidated by backstop mechanism
"settlement"
position was closed due to Auto-Deleveraging (ADL) or other settlement
'next_cursor'stringNext cursor for pagination
'has_more'booleanTrue if there exists a 'next_cursor'
| Field | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'event_type'` | string |

"fulfill\_taker" if maker
"fulfill\_maker" if taker

| | `'side'` | string |

"open\_long"
"open\_short"
"close\_long"
"close\_short"

| | `'cause'` | string |

"normal"
regular user-initiated trading
"market\_liquidation" position was liquidated due to insufficient margin
"backstop\_liquidation" position was liquidated by backstop mechanism
"settlement"
position was closed due to Auto-Deleveraging (ADL) or other settlement

| * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/trades/history?account=42trU9A5...&symbol=BTC&limit=20&cursor=11115hVka", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get funding history This endpoint allows users to get funding history. ``` GET /api/v1/funding/history ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredTrading pair symbol42trU9A5...
"limit"integeroptionalMaximum number of records to return default system defined limit100
"cursor"stringoptionalCursor pagination to access records. Default to none1115hVka
``` /api/v1/funding/history?account=42trU9A5...&limit=20&cursor=11115hVka ``` #### Response * Status 200: Successfully retrieved funding history ```json { "success": true, "data": [ { "history_id": 2287920, "symbol": "PUMP", "side": "ask", "amount": "39033804", "payout": "2.617479", "rate": "0.0000125", "created_at": 1759222804122 }, ... ], "next_cursor": "11114Lz77", "has_more": true } ```
FieldTypeDescription
"history_id"integerHistory id of trade
"symbol"stringTrading pair symbol
"side"stringIf the position resulting in the funding payment was long or short (bid or ask)
"amount"decimal stringAmount (in token denomination) of the position that resulted in the funding payment
"payout"decimal stringFunding paid (in USD)
"rate"decimal stringFunding rate that was used to calculate the payput
"created_at"integerTimestamp in milliseconds when the funding payment was logged
'next_cursor'stringNext cursor for pagination
'has_more'booleanTrue if there exists a 'next_cursor'
* Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/funding/history?account=42trU9A5...&limit=20&cursor=11115hVka", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get account equity history This endpoint allows users to get account equity and PnL history (over time). ``` GET /api/v1/portfolio ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"time_range"stringrequiredTime range of history: 1d, 7d, 14d, 30d, all7d
"start_time"integeroptionalStart time in milliseconds1760271000000
"end_time"integeroptionalEnd time in milliseconds1761842220000
"limit"integeroptionalMaximum number of records to return, defaults to 100100
``` /api/v1/portfolio?account=42trU9A5...&time_range=7d ``` #### Response * Status 200: Successfully retrieved portfolio history ```json { "success": true, "data": [ { "account_equity": "61046.308885", "pnl": "9297.553505", "timestamp": 1761177600000 }, ... ], "error": null, "code": null } ``` | Field | Type | Description | | ------------------ | -------------- | -------------------------------------------------------- | | `'account_equity'` | decimal string | Account equity (balance + unrealized PnL) at last update | | `'PnL'` | decimal string | PnL of account since creation | | `'timestamp'` | integer | Timestamp in milliseconds of last account equity update | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/portfolio?account=42trU9A5...&time_range=7d", headers={"Accept": "*/*"}, ) data = response.json() ``` # Get account balance history This endpoint allows users to get account balance history. Returns all balance effects that affects the queried account. ``` GET /api/v1/account/balance/history ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"limit"integeroptionalMaximum number of records to return, defaults to system defined limit100
"cursor"stringoptionalCursor pagination to access records. Default to none1115hVka
``` /api/v1/account/balance/history?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved balance history ```json { "success": true, "data": [ { "amount": "100.000000", "balance": "1200.000000", "pending_balance": "0.000000", "event_type": "deposit", "created_at": 1716200000000 } ... ], "next_cursor": "11114Lz77", "has_more": true } ``` | Field | Type | Description | | ------------------- | -------------- | ------------------------------------------------------------ | | `'amount'` | decimal string | Amount change to balance after event | | `'balance'` | decimal string | Account balance after event | | `'pending_balance'` | decimal string | Pending balance after event | | `'event_type'` | string | Type of balance event (see below) | | `'created_at'` | integer | Timestamp in milliseconds of when the balance event occurred | | `'next_cursor'` | string | Next cursor for pagination | | `'has_more'` | boolean | True if there exists a `'next_cursor'` | | Event Type (String) | Description | | ------------------------ | ------------------------------------------ | | `'deposit'` | Deposit funds to account | | `'deposit_release'` | Release of previously pending deposit | | `'withdraw'` | Withdrawal of funds from account | | `'trade'` | Trading activity (fees, realized PnL) | | `'market_liquidation'` | Liquidation by market orders | | `'backstop_liquidation'` | Liquidation by backstop liquidator | | `'adl_liquidation'` | Liquidation by auto-deleveraging | | `'subaccount_transfer'` | Transfer between subaccounts | | `'funding'` | Funding payment | | `'payout'` | Payout event (from e.g. affiliate program) | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/portfolio?account/balance/history?account=42trU9A5..." headers={"Accept": "*/*"}, ) data = response.json() ``` # Request withdrawal This endpoint allows users to request withdrawal. ``` POST /api/v1/account/withdraw ``` #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5j1Vy9Uq...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"amount"stringrequiredAmount to withdraw in USDC100.50
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5j1Vy9Uq...", "timestamp": 1716200000000, "amount": "100.50", "agent_wallet": "69trU9A5...", "expiry_window": 30000, } ``` #### Response * Status 200: Success ```json { "success": true } ``` * Status 400: Invalid request parameters * Status 500: Internal server error #### Code Example (Python) ```python import requests payload = { "account": "42trU9A5...", "signature": "5j1Vy9Uq...", "timestamp": 1716200000000, "amount": "100.50" } response = requests.post( "/api/v1/account/withdraw", json=payload, headers={"Content-Type": "application/json"} ) data = response.json() ``` # Get account loan info This endpoint returns loan and collateral information for a given account under unified margin. ``` GET /api/v1/account/loan ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredAccount address42trU9A5...
``` /api/v1/account/loan?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved account loan info ```json { "success": true, "data": { "borrowed": "1250.500000", "pending_interest": "3.250000", "collateral_utilization": "0.45", "total_interest_earned": "120.750000", "total_interest_paid": "85.300000", "spot_balances": [ { "symbol": "SOL", "amount": "10.00000000", "ltv_ratio": "0.90", "market_value": "1500.000000", "collateral_value": "1350.000000" } ], "updated_at": 1716200000000 }, "error": null, "code": null } ``` | Field | Type | Description | | -------------------------- | -------------- | ------------------------------------------------------------------------------ | | `'borrowed'` | decimal string | Current borrowed amount in USD | | `'pending_interest'` | decimal string | Accrued interest not yet repaid | | `'collateral_utilization'` | decimal string | Ratio of borrowed amount to total spot collateral capacity | | `'total_interest_earned'` | decimal string | Total interest earned as a lender (cumulative) | | `'total_interest_paid'` | decimal string | Total interest paid as a borrower (cumulative, returned as positive) | | `'spot_balances'` | array | Spot balances with their effective LTV and collateral contribution (see below) | | `'updated_at'` | integer | Timestamp in milliseconds of last data update | **Spot Balance Fields** | Field | Type | Description | | -------------------- | -------------- | ------------------------------------------------------------------- | | `'symbol'` | string | Spot asset symbol | | `'amount'` | decimal string | Spot balance amount | | `'ltv_ratio'` | decimal string | Effective LTV ratio used for loan collateral | | `'market_value'` | decimal string | Raw marked-to-market USD value of this positive spot balance | | `'collateral_value'` | decimal string | Effective collateral contribution of this asset after LTV/cap logic | * Status 404: Account loan cache not found * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/account/loan", params={"account": "42trU9A5..."}, headers={"Accept": "*/*"}, ) data = response.json() ``` # Add isolated margin This endpoint allows users to add margin to an isolated position. ``` POST /api/v1/positions/add_isolated_margin ``` The operation type for signing is `"add_isolated_margin"`. Transfers USDC from free balance into the isolated margin pool for the specified position. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"symbol"stringrequiredTrading pair symbolBTC-PERP
"amount"stringrequiredAmount of USDC to add as margin100.000000
"agent_wallet"stringoptionalAgent wallet address8zFqj1Kp...
"expiry_window"integeroptionalSignature expiry in milliseconds10000
#### Response * Status 200: Successfully added isolated margin ```json { "success": true } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests payload = { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "symbol": "BTC-PERP", "amount": "100.000000", } response = requests.post( "/api/v1/positions/add_isolated_margin", json=payload, headers={"Accept": "*/*"}, ) data = response.json() ``` # Update spot settings This endpoint allows users to update spot asset settings for unified margin. ``` POST /api/v1/account/settings/spot ``` The operation type for signing is `"update_account_spot_settings"`. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"symbol"stringrequiredSpot asset symbolSOL
"unified_margin_excluded"booleanrequiredWhether to exclude this asset from unified margin collateraltrue
"agent_wallet"stringoptionalAgent wallet address8zFqj1Kp...
"expiry_window"integeroptionalSignature expiry in milliseconds10000
#### Response * Status 200: Successfully updated spot settings ```json { "success": true } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests payload = { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "symbol": "SOL", "unified_margin_excluded": True, } response = requests.post( "/api/v1/account/settings/spot", json=payload, headers={"Accept": "*/*"}, ) data = response.json() ``` # Toggle auto-lending This endpoint allows users to enable or disable automatic lending. ``` POST /api/v1/account/settings/auto_lend_disabled ``` The operation type for signing is `"set_auto_lend_disabled"`. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"disabled"boolean or nulloptionalSet to true to disable auto-lending, false to enable, or null to clear (return to default)true
"agent_wallet"stringoptionalAgent wallet address8zFqj1Kp...
"expiry_window"integeroptionalSignature expiry in milliseconds10000
#### Response * Status 200: Successfully updated auto-lending setting ```json { "success": true } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests # Disable auto-lending payload = { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "disabled": True, } response = requests.post( "/api/v1/account/settings/auto_lend_disabled", json=payload, headers={"Accept": "*/*"}, ) data = response.json() ``` # Get spot balance history This endpoint allows users to get spot asset balance history. ``` GET /api/v1/account/spot_balance/history ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"symbol"stringoptionalFilter by spot asset symbolSOL
"limit"integeroptionalMaximum number of records to return, defaults to system defined limit100
"cursor"stringoptionalCursor for pagination. Default to none1115hVka
``` /api/v1/account/spot_balance/history?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved spot balance history ```json { "success": true, "data": [ { "amount": "1.00000000", "balance": "5.50000000", "symbol": "SOL", "event_type": "deposit", "created_at": 1716200000000 } ... ], "next_cursor": "11114Lz77", "has_more": true } ``` | Field | Type | Description | | --------------- | -------------- | ---------------------------------------------------- | | `'amount'` | decimal string | Amount change to balance after event | | `'balance'` | decimal string | Balance after event | | `'symbol'` | string | Spot asset symbol | | `'event_type'` | string | Type of balance event | | `'created_at'` | integer | Timestamp in milliseconds of when the event occurred | | `'next_cursor'` | string | Next cursor for pagination | | `'has_more'` | boolean | True if there exists a `'next_cursor'` | * Status 400: Invalid request parameters * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/account/spot_balance/history", params={"account": "42trU9A5..."}, headers={"Accept": "*/*"}, ) data = response.json() ``` # Withdraw spot asset This endpoint allows users to withdraw a spot asset. ``` POST /api/v1/account/spot_asset/withdraw ``` The operation type for signing is `"withdraw_spot_asset"`. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"symbol"stringrequiredSpot asset symbolSOL
"amount"stringrequiredAmount to withdraw1.00000000
"idempotency_key"stringoptionalFull UUID string. Prevents duplicate withdrawals550e8400-e29b-41d4-a716-446655440000
"agent_wallet"stringoptionalAgent wallet address8zFqj1Kp...
"expiry_window"integeroptionalSignature expiry in milliseconds10000
#### Response * Status 200: Successfully submitted withdrawal ```json { "success": true, "data": { "symbol": "SOL", "batch_nonce": 42, "requested_amount": "1.00000000", "fee_amount": "0.00100000" } } ``` | Field | Type | Description | | -------------------- | -------------- | -------------------------------- | | `'symbol'` | string | Spot asset symbol | | `'batch_nonce'` | integer | Nonce of the withdrawal batch | | `'requested_amount'` | decimal string | Amount requested for withdrawal | | `'fee_amount'` | decimal string | Fee deducted from the withdrawal | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 409: Duplicate idempotency key * Status 500: Internal server error #### Code Example (Python) ```python import requests payload = { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "symbol": "SOL", "amount": "1.00000000", } response = requests.post( "/api/v1/account/spot_asset/withdraw", json=payload, headers={"Accept": "*/*"}, ) data = response.json() ``` # Get pending spot withdrawals This endpoint returns pending spot asset withdrawals. ``` GET /api/v1/account/spot_asset/withdraw/pending ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
``` /api/v1/account/spot_asset/withdraw/pending?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved pending spot withdrawals ```json { "success": true, "data": [ { "symbol": "SOL", "amount": "1.00000000", "amount_requested": "1.00100000", "fee_amount": "0.00100000", "batch_nonce": 42, "created_at": 1716200000000 } ... ] } ``` | Field | Type | Description | | -------------------- | -------------- | ------------------------------------------------------------ | | `'symbol'` | string | Spot asset symbol | | `'amount'` | decimal string | Net amount to be received after fees | | `'amount_requested'` | decimal string | Original amount requested for withdrawal | | `'fee_amount'` | decimal string | Fee deducted from the withdrawal | | `'batch_nonce'` | integer | Nonce of the withdrawal batch | | `'created_at'` | integer | Timestamp in milliseconds of when the withdrawal was created | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/account/spot_asset/withdraw/pending", params={"account": "42trU9A5..."}, headers={"Accept": "*/*"}, ) data = response.json() ``` # Get spot deposit history This endpoint returns spot asset deposit history. ``` GET /api/v1/account/spot_asset/deposit/history ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"limit"integeroptionalMaximum number of records to return, defaults to system defined limit100
"cursor"stringoptionalCursor for pagination. Default to none1115hVka
``` /api/v1/account/spot_asset/deposit/history?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved spot deposit history ```json { "success": true, "data": [ { "symbol": "SOL", "amount": "1.50000000", "transaction_id": "5xGk...", "created_at": 1716200000000 } ... ], "next_cursor": "11114Lz77", "has_more": true } ``` | Field | Type | Description | | ------------------ | -------------- | ------------------------------------------------------ | | `'symbol'` | string | Spot asset symbol | | `'amount'` | decimal string | Amount deposited | | `'transaction_id'` | string | On-chain transaction identifier | | `'created_at'` | integer | Timestamp in milliseconds of when the deposit occurred | | `'next_cursor'` | string | Next cursor for pagination | | `'has_more'` | boolean | True if there exists a `'next_cursor'` | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/account/spot_asset/deposit/history", params={"account": "42trU9A5..."}, headers={"Accept": "*/*"}, ) data = response.json() ``` # Get spot withdrawal history This endpoint returns spot asset withdrawal history. ``` GET /api/v1/account/spot_asset/withdraw/history ``` #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringrequiredUser's wallet address42trU9A5...
"limit"integeroptionalMaximum number of records to return, defaults to system defined limit100
"cursor"stringoptionalCursor for pagination. Default to none1115hVka
``` /api/v1/account/spot_asset/withdraw/history?account=42trU9A5... ``` #### Response * Status 200: Successfully retrieved spot withdrawal history ```json { "success": true, "data": [ { "symbol": "SOL", "amount": "1.00000000", "batch_nonce": 42, "transaction_id": "5xGk...", "created_at": 1716200000000 } ... ], "next_cursor": "11114Lz77", "has_more": true } ``` | Field | Type | Description | | ------------------ | -------------- | --------------------------------------------------------- | | `'symbol'` | string | Spot asset symbol | | `'amount'` | decimal string | Amount withdrawn | | `'batch_nonce'` | integer | Nonce of the withdrawal batch | | `'transaction_id'` | string | On-chain transaction identifier | | `'created_at'` | integer | Timestamp in milliseconds of when the withdrawal occurred | | `'next_cursor'` | string | Next cursor for pagination | | `'has_more'` | boolean | True if there exists a `'next_cursor'` | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error #### Code Example (Python) ```python import requests response = requests.get( "/api/v1/account/spot_asset/withdraw/history", params={"account": "42trU9A5..."}, headers={"Accept": "*/*"}, ) data = response.json() ``` # Vaults REST API endpoints for creating, funding, configuring, and listing vaults. Pacifica's user-facing docs call these managed pools **vaults**, while the REST API namespace currently uses `/api/v1/lake/*`. ## Endpoints * [Create vault](/docs/api-documentation/api/rest-api/vaults/create-vault) * [Claim vault referral code](/docs/api-documentation/api/rest-api/vaults/claim-vault-referral-code) * [Deposit to vault](/docs/api-documentation/api/rest-api/vaults/deposit-to-vault) * [Claim vault manager](/docs/api-documentation/api/rest-api/vaults/claim-vault-manager) * [Withdraw from vault](/docs/api-documentation/api/rest-api/vaults/withdraw-from-vault) * [Update vault deposit cap](/docs/api-documentation/api/rest-api/vaults/update-vault-deposit-cap) * [Add vault whitelist](/docs/api-documentation/api/rest-api/vaults/add-vault-whitelist) * [Remove vault whitelist](/docs/api-documentation/api/rest-api/vaults/remove-vault-whitelist) * [Add vault blacklist](/docs/api-documentation/api/rest-api/vaults/add-vault-blacklist) * [Remove vault blacklist](/docs/api-documentation/api/rest-api/vaults/remove-vault-blacklist) * [Add vault max leverage](/docs/api-documentation/api/rest-api/vaults/add-vault-max-leverage) * [Remove vault max leverage](/docs/api-documentation/api/rest-api/vaults/remove-vault-max-leverage) * [List vaults](/docs/api-documentation/api/rest-api/vaults/list-vaults) # Create vault Create a new vault (lake) and optionally set its initial configuration and seed deposit. ``` POST /api/v1/lake/create ``` The operation type for signing is `"create_lake"`. This endpoint creates a new vault and returns its generated account address. The API path uses `lake`, but this feature is referred to as `vaults` in user-facing docs. `manager_loss_share` is currently disabled; omit it or pass `"0"`. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredSignature over the sorted request payload5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"manager"stringoptionalManager address. Omit to create a fresh vault with no manager.8zFqj1Kp...
"nickname"stringoptionalDisplay name for the vaultBTC Basis Vault
"deposit_cap"decimal stringoptionalMaximum LP balance accepted by the vault1000000
"manager_profit_share"decimal stringoptionalPerformance fee fraction in [0,1]0.20
"manager_loss_share"decimal stringoptionalTemporarily disabled; only "0" is accepted0
"deposit_min_duration_ms"integeroptionalMinimum deposit lock duration in milliseconds86400000
"manager_min_balance_portion"decimal stringoptionalManager balance ratio required to claim or re-enable the vault0.10
"manager_liquidation_balance_portion"decimal stringoptionalManager balance ratio that triggers trading halt and liquidation0.05
"initial_deposit"decimal stringoptionalSeed deposit from the creator in the same request1000.00
"withdraw_window_s"integeroptionalWithdrawal cycle period in seconds2592000
"withdraw_duration_s"integeroptionalOpen withdrawal time per cycle in seconds259200
"referral_code"stringoptionalReferral code to claim for the new vaulttestcode
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "nickname": "BTC Basis Vault", "manager_profit_share": "0.20", "deposit_cap": "1000000", "deposit_min_duration_ms": 86400000, "manager_min_balance_portion": "0.10", "manager_liquidation_balance_portion": "0.05", "initial_deposit": "1000.00", "withdraw_window_s": 2592000, "withdraw_duration_s": 259200, "referral_code": "testcode", "expiry_window": 30000 } ``` #### Response * Status 200: Vault created successfully ```json { "success": true, "data": { "lake_address": "AbCdEfGh123456789...", "referral_claimed": true }, "error": null, "code": null } ``` | Field | Type | Description | | -------------------- | ------- | ----------------------------------------------------------- | | `'lake_address'` | string | Generated vault account address | | `'referral_claimed'` | boolean | Whether the optional referral code was claimed successfully | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error # Claim vault referral code Claim a referral code for an existing vault. ``` POST /api/v1/lake/claim_referral_code ``` The operation type for signing is `"claim_lake_referral"`. Only the vault creator can claim a referral code for an existing vault. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"code"stringrequiredReferral code to claimtestcode
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "code": "testcode" } ``` #### Response * Status 200: Referral code claimed successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters or caller is not the vault creator * Status 401: Unauthorized access * Status 500: Internal server error # Deposit to vault Deposit funds into a vault and receive vault shares. ``` POST /api/v1/lake/deposit ``` The operation type for signing is `"deposit_to_lake"`. Use this endpoint to deposit USDC from an account into a vault. Deposits are idempotent when an `idempotency_key` is supplied. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredDepositor wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"amount"decimal stringrequiredDeposit amount in USDC1000.00
"idempotency_key"UUID stringoptionalClient-generated key to prevent duplicate deposits550e8400-e29b-41d4-a716-446655440000
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "amount": "1000.00", "idempotency_key": "550e8400-e29b-41d4-a716-446655440000" } ``` #### Response * Status 200: Deposit successful ```json { "success": true, "data": { "shares_minted": "1000.00" }, "error": null, "code": null } ``` | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------- | | `'shares_minted'` | decimal string | Number of vault shares minted to the depositor | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 409: Duplicate idempotency key * Status 500: Internal server error # Claim vault manager Claim the manager role on a fresh vault. ``` POST /api/v1/lake/claim_manager ``` The operation type for signing is `"claim_lake_manager"`. This endpoint is only for fresh vaults that were created without a manager. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredClaimer wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"deposit_amount"decimal stringrequiredManager's initial deposit amount1000.00
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "deposit_amount": "1000.00" } ``` #### Response * Status 200: Manager claim successful ```json { "success": true, "data": { "shares_minted": "1000.00" }, "error": null, "code": null } ``` | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------- | | `'shares_minted'` | decimal string | Number of manager shares minted to the claimer | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 500: Internal server error # Withdraw from vault Redeem vault shares and withdraw funds from a vault. ``` POST /api/v1/lake/withdraw ``` The operation type for signing is `"withdraw_from_lake"`. Use this endpoint to redeem shares from a vault. Withdrawals are idempotent when an `idempotency_key` is supplied. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredDepositor wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"shares"decimal stringrequiredNumber of shares to redeem50.00
"idempotency_key"UUID stringoptionalClient-generated key to prevent duplicate withdrawals550e8400-e29b-41d4-a716-446655440000
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "shares": "50.00", "idempotency_key": "550e8400-e29b-41d4-a716-446655440000" } ``` #### Response * Status 200: Withdrawal successful ```json { "success": true, "data": { "amount_withdrawn": "500.00" }, "error": null, "code": null } ``` | Field | Type | Description | | -------------------- | -------------- | ------------------------------ | | `'amount_withdrawn'` | decimal string | USDC returned to the depositor | * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 409: Duplicate idempotency key * Status 500: Internal server error # Update vault deposit cap Update or clear the deposit cap for a vault. ``` POST /api/v1/lake/update_deposit_cap ``` The operation type for signing is `"update_lake_deposit_cap"`. Only the vault creator can call this endpoint. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"deposit_cap"decimal string or nulloptionalNew LP deposit cap. Set to null to remove the cap.2000000
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "deposit_cap": "2000000" } ``` #### Response * Status 200: Deposit cap updated successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 403: Caller is not the vault creator * Status 500: Internal server error # Add vault whitelist Add tradable symbols to a vault whitelist. ``` POST /api/v1/lake/add_whitelist ``` The operation type for signing is `"add_lake_whitelist"`. Only the vault creator can call this endpoint. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"symbols"string arrayrequiredSymbols to add to the whitelist["BTC", "ETH"]
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "symbols": ["BTC", "ETH"] } ``` #### Response * Status 200: Whitelist updated successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 403: Caller is not the vault creator * Status 500: Internal server error # Remove vault whitelist Remove tradable symbols from a vault whitelist. ``` POST /api/v1/lake/remove_whitelist ``` The operation type for signing is `"remove_lake_whitelist"`. Only the vault creator can call this endpoint. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"symbols"string arrayrequiredSymbols to remove from the whitelist["BTC", "ETH"]
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "symbols": ["BTC", "ETH"] } ``` #### Response * Status 200: Whitelist updated successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 403: Caller is not the vault creator * Status 500: Internal server error # Add vault blacklist Add blocked symbols to a vault blacklist. ``` POST /api/v1/lake/add_blacklist ``` The operation type for signing is `"add_lake_blacklist"`. Only the vault creator can call this endpoint. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"symbols"string arrayrequiredSymbols to add to the blacklist["BTC", "ETH"]
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "symbols": ["BTC", "ETH"] } ``` #### Response * Status 200: Blacklist updated successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 403: Caller is not the vault creator * Status 500: Internal server error # Remove vault blacklist Remove blocked symbols from a vault blacklist. ``` POST /api/v1/lake/remove_blacklist ``` The operation type for signing is `"remove_lake_blacklist"`. Only the vault creator can call this endpoint. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"symbols"string arrayrequiredSymbols to remove from the blacklist["BTC", "ETH"]
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "symbols": ["BTC", "ETH"] } ``` #### Response * Status 200: Blacklist updated successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 403: Caller is not the vault creator * Status 500: Internal server error # Add vault max leverage Add per-symbol max leverage limits for a vault. ``` POST /api/v1/lake/add_max_leverage ``` The operation type for signing is `"add_lake_max_leverage"`. Only the vault creator can call this endpoint. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"symbols"string arrayrequiredSymbols that should receive the same max leverage cap["BTC", "ETH"]
"max_leverage"decimal stringrequiredMaximum leverage to apply to every listed symbol10
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "symbols": ["BTC", "ETH"], "max_leverage": "10" } ``` #### Response * Status 200: Max leverage updated successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 403: Caller is not the vault creator * Status 500: Internal server error # Remove vault max leverage Remove per-symbol max leverage limits from a vault. ``` POST /api/v1/lake/remove_max_leverage ``` The operation type for signing is `"remove_lake_max_leverage"`. Only the vault creator can call this endpoint. #### Request Body
FieldTypeNeedDescriptionExample
"account"stringrequiredCreator wallet address42trU9A5...
"signature"stringrequiredCryptographic signature5J3mBbAH...
"timestamp"integerrequiredCurrent timestamp in milliseconds1716200000000
"lake"stringrequiredVault addressAbCdEfGh123456789...
"symbols"string arrayrequiredSymbols whose custom max leverage should be removed["BTC", "ETH"]
"agent_wallet"stringoptionalAgent wallet address69trU9A5...
"expiry_window"integeroptionalSignature expiry in milliseconds30000
```json { "account": "42trU9A5...", "signature": "5J3mBbAH...", "timestamp": 1716200000000, "lake": "AbCdEfGh123456789...", "symbols": ["BTC", "ETH"] } ``` #### Response * Status 200: Max leverage removed successfully ```json { "success": true, "data": { "success": true }, "error": null, "code": null } ``` * Status 400: Invalid request parameters * Status 401: Unauthorized access * Status 403: Caller is not the vault creator * Status 500: Internal server error # List vaults List all vaults and optionally include the querying account's share balance. ``` GET /api/v1/lake/list ``` Returns all vaults ordered by creation time descending. If `account` is provided, the response also includes that account's share balance in each vault as `user_share`. #### Query Parameters
FieldTypeNeedDescriptionExample
"account"stringoptionalAccount address whose share balance should be included42trU9A5...
``` /api/v1/lake/list?account=42trU9A5... ``` #### Response * Status 200: List of vaults ```json { "success": true, "data": { "lakes": [ { "address": "AbCdEfGh123456789...", "creator": "42trU9A5...", "manager": "8zFqj1Kp...", "nickname": "BTC Basis Vault", "lp_shares": "900000.00", "manager_shares": "100000.00", "lp_balance": "910000.00", "manager_balance": "115000.00", "last_checked_equity": "1025000.00", "high_watermark": "1025000.00", "created_at": 1700000000000, "referrer": "7xyReferrer...", "user_share": "500.00", "config": { "deposit_cap": "1000000.00", "manager_profit_share": "0.20", "manager_loss_share": "0", "deposit_min_duration_ms": 86400000, "manager_min_balance_portion": "0.10", "manager_liquidation_balance_portion": "0.05", "withdraw_window_s": 2592000, "withdraw_duration_s": 259200 } } ] }, "error": null, "code": null } ``` **Lake fields** | Field | Type | Description | | ----------------------- | ---------------------- | ----------------------------------------------------------------- | | `'address'` | string | Vault account address | | `'creator'` | string | Creator address | | `'manager'` | string or null | Current manager address | | `'nickname'` | string or null | Optional vault nickname | | `'lp_shares'` | decimal string | Total LP shares outstanding | | `'manager_shares'` | decimal string | Total manager shares outstanding | | `'lp_balance'` | decimal string | Balance attributed to LP shares | | `'manager_balance'` | decimal string | Balance attributed to manager shares | | `'last_checked_equity'` | decimal string | Most recent equity snapshot used for vault accounting | | `'high_watermark'` | decimal string | High-water mark for performance fee accounting | | `'created_at'` | integer | Vault creation timestamp in milliseconds | | `'referrer'` | string or null | Referrer address if a referral code was claimed | | `'user_share'` | decimal string or null | Share balance for the queried account, when `account` is provided | | `'config'` | object or null | Vault configuration, when present | **Config fields** | Field | Type | Description | | --------------------------------------- | ---------------------- | ---------------------------------- | | `'deposit_cap'` | decimal string or null | LP deposit cap | | `'manager_profit_share'` | decimal string or null | Performance fee fraction | | `'manager_loss_share'` | decimal string or null | Manager loss share setting | | `'deposit_min_duration_ms'` | integer or null | Minimum deposit duration | | `'manager_min_balance_portion'` | decimal string or null | Required manager balance ratio | | `'manager_liquidation_balance_portion'` | decimal string or null | Halt/liquidation trigger ratio | | `'withdraw_window_s'` | integer or null | Withdrawal cycle period | | `'withdraw_duration_s'` | integer or null | Open withdrawal duration per cycle | * Status 500: Internal server error --- [Next Page](https://pacifica.gitbook.io/docs/llms-full.txt/1)