Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pacifica-fi/docs-migrate/llms.txt
Use this file to discover all available pages before exploring further.
Pacifica’s spot markets let you buy and sell base assets directly against USDC on the same high-performance orderbook used for perpetuals. Unlike perpetuals, spot positions carry no leverage, no funding rates, and no liquidation risk tied to mark-price divergence — you simply own the asset at whatever price you paid. Spot holdings are also first-class citizens in the unified cross-margin system: they can back perpetual positions and earn passive yield when left idle, making a single Pacifica account serve as both a trading terminal and a light-weight money market account.
Spot vs. Perpetuals
| Feature | Spot | Perpetuals |
|---|
| Effective leverage | 1× (no leverage) | Up to exchange max |
| Funding rate | None | Yes (periodic) |
| Settlement | Immediate delivery of base asset | Cash-settled in USDC |
reduce_only orders | Not supported (rejected) | Supported |
| Collateral contribution | Yes (LTV-discounted) | N/A |
Order Types and Fees
Spot markets accept Market, Limit, Stop Market, and Stop Limit orders. Time-in-force options are GTC, IOC, ALO, and TOB. Orders flagged reduce_only are rejected on spot markets.
Fees are deducted from the asset you receive at the end of each trade:
buy: received_base = (usdc_spent / price) * (1 - fee_rate)
sell: received_usdc = (base_sold * price) * (1 - fee_rate)
Balance Locks
Placing an open spot order locks the relevant balance until the order fills or is cancelled. Locked balance does not earn auto-lending yield and has a reduced effect on cross-margin collateral.
| Order 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
Every eligible spot asset you hold contributes collateral value to your cross-margin account. This lets a single account hold spot positions, short perpetuals, and have them all count toward the same margin pool.
Collateral Parameters
Each asset is governed by four parameters published via GET /api/v1/spot_assets:
| Parameter | Description |
|---|
collateral_enabled | If false, the asset contributes zero collateral regardless of balance. |
ltv_ratio | Loan-to-value ratio (0–1). Typical values: 0.90 for BTC/ETH, 0.80 for majors. |
spread_divisor | Optional hedging bonus multiplier applied to any balance offset by a cross-margin short. Active only when spread_divisor > 1. |
collateral_value_limit_usd | Per-(user, asset) cap on gross market value eligible for collateral. Default: 10,000 USDC. |
The per-user cap can be raised by admin override. Units beyond capped_units remain fully tradeable — they simply contribute no additional collateral value.
Collateral Calculation
For a spot balance B, oracle price P, and hedged size H (the portion offset by a cross-margin short perpetual — isolated shorts do not count):
base_rate = ltv_ratio * P
bonus_rate = P * (1 - ltv_ratio) * (1 - 1 / spread_divisor) (0 when spread_divisor <= 1)
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
ltv_ratio × collateral_value_limit_usd — for example, 9,000 USDC at ltv_ratio = 0.9 and the 10,000 USDC 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:
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
spot_collateral_value ≈ 121.4286 * 50 + 120 * 50 ≈ 12,071.4
120 × 100 = 12,000 USDC. The short adds ~71.4 USDC of additional collateral.
Opting Out of Unified Margin
Set unified_margin_excluded = true on a (user, asset) pair to remove that asset’s collateral contribution. The balance stays in the account and is fully tradeable and withdrawable — it simply no longer backs perpetual margin.
Auto-Lending (Money Market)
Idle USDC in your account is automatically lent to the pool and earns interest. Lending and borrowing are implicit — there is nothing to enable.
How Lending Works
Your account is eligible to lend when:
- Your USDC balance is at least 1,000 USDC.
- Your lendable capacity (USDC balance net of the 10 % initial-margin floor, pending interest, and USDC locked by open spot buy orders) is also at least 1,000 USDC.
auto_lend_disabled is false.
Lender APR is derived pro-rata from the pool’s utilization:
lend_apr = borrow_apr * utilization
APY ≈ e^APR − 1.
How Borrowing Works
An account automatically borrows when perpetual losses push its USDC equity below zero, provided it holds sufficient spot collateral. Borrowing is not a separate action — it happens implicitly when:
equity_without_spot = usdc_balance + unrealized_pnl_from_cross_perps - pending_interest
required_borrow = max(0, -equity_without_spot)
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.
Pool Aggregates
Pool-wide utilization is computed from the aggregate lendable capacity and active borrows:
total_borrowable = sum over eligible lenders of their lendable capacity
total_borrowed = sum over borrowers of required_borrow
utilization = total_borrowed / total_borrowable
GET /api/v1/loan_pool.
Interest Rates
Borrow APR follows a piecewise utilization curve:
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)
MIN_BORROW_APR = 1%, LINEAR_KINK_APR = 10.95%, EXPONENTIAL_TARGET_APR = 50%.
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; spot orders are not subject to this check |
| Pool deleveraging | ≥ 95% | Pool-level insolvency deleveraging begins |
| Pool deleveraging target | 90% | Utilization target after pool-level deleveraging |
pending_interest grows by:
pending_interest += required_borrow * borrow_rate_per_second * 60
pending_interest is charged to the borrower’s USDC balance and distributed pro-rata across lenders’ USDC balances every hour.
Opting Out of Auto-Lending
Set auto_lend_disabled = true to stop lending. Your USDC balance remains fully usable for trading but is excluded from total_borrowable and earns no yield. Borrowing itself cannot be disabled — if equity_without_spot drops below zero with sufficient spot collateral, a loan opens automatically.
Cross Margin Only
Spot on Pacifica uses cross margin only. There is no isolated margin mode for spot assets. All spot balances and their collateral contributions are pooled across your single cross-margin account.
Withdrawing Spot Assets
You can withdraw any spot asset at any time, subject to the standard available_to_withdraw check. The withdrawal reduces spot_collateral_value by the withdrawn units’ LTV-adjusted value. If the withdrawal would leave your open positions under-margined, it will be rejected until you reduce position size or add collateral.
Close or reduce open sell orders before withdrawing to unlock the base asset balance first. Locked units are not available to withdraw until the order is filled or cancelled.
API Reference
Full REST endpoints for placing spot orders, querying spot balances, and reading asset parameters are documented at /api/rest/spot.