> ## Documentation Index
> Fetch the complete documentation index at: https://scalarfield.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Trading on Jupiter DEX

> Trade Solana tokens on Jupiter DEX through Scalar Field — J: ticker semantics, swap execution via a managed Solana wallet, tokenized equities and pre-IPO tokens, and the Jupiter data functions.

<Info>**Execution:** `venue.trade()` in chat code, `strategy.execute()` in strategy agents. **Data reference:** [Jupiter Data](/market-data/jupiter-data).</Info>

# Overview

Jupiter is a DEX aggregator on Solana that routes swaps across the chain's liquidity venues (Raydium, Orca, Meteora, and others). Scalar Field connects to it through a managed, self-custodial Solana wallet (`WALLET_SOL`): the wallet holds USDC and token positions, and orders are executed as Jupiter swaps.

The tradeable universe is any Jupiter-verified Solana token. This includes tokenized equities (xStocks such as tokenized AAPL and NVDA) and pre-IPO tokens (SpaceX, OpenAI, Anthropic, Anduril), which trade continuously, including outside US market hours.

| Specification      | Value                                                                            |
| ------------------ | -------------------------------------------------------------------------------- |
| Instruments        | Jupiter-verified Solana tokens — xStocks, pre-IPO tokens, LSTs, other SPL tokens |
| Symbols            | `J:<mint_address>`                                                               |
| Hours              | 24/7                                                                             |
| Fill model         | Synchronous ExactIn swaps                                                        |
| Slippage tolerance | `slippage_bps`, default 50 (0.5%)                                                |
| Fractional         | Yes                                                                              |
| Currency           | USDC in the Solana wallet                                                        |

# Order Semantics

* **Symbols are `J:`-prefixed mint addresses** (e.g. `J:DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263`). Plain symbols like `BONK` are not accepted — symbols are ambiguous on Solana because lookalike tokens share them. Resolve tokens with `searchJupiterTokens()` or `screenJupiterTokens()`.
* **Swaps are ExactIn**: the requested quantity is converted to USDC at the current price, so `filled_qty` may differ slightly from the request due to slippage. Read actual holdings back from `venue.positions()` rather than assuming the requested quantity.
* **Fills are synchronous** — `venue.trade()` blocks until the swap confirms or fails. `tx_hash` in the response is the Solana transaction signature.
* **Fractional quantities are supported.** Size from a dollar budget with `round(budget / price, 2)`.
* A platform referral fee is collected on-chain during the swap; `fee_bps` and `fee_amount` appear in the trade response when active.

# Connecting and Funding

1. Scalar Field provisions a managed, self-custodial Solana wallet (`WALLET_SOL`) — no external wallet is required.
2. Fund the wallet with USDC from the portfolio page. Wallet balances and positions are readable on-chain at any time.

# Usage

```python theme={null}
from scalarlib import searchJupiterTokens, venue

# Resolve a token to its J: ticker
tokens = searchJupiterTokens("anthropic")
ticker = tokens.iloc[0]["ticker"]            # 'J:<mint>'

# Swap: buy 5 tokens through the managed wallet
resp = venue.trade("buy", ticker, 5, account="WALLET_SOL")
print(resp["status"], resp["filled_qty"], resp["avg_price"])

# Sell with a wider slippage tolerance
resp = venue.trade("sell", ticker, 2.5, account="WALLET_SOL", slippage_bps=100)
```

In strategy agents, use `strategy.execute(ticker, target_qty)` instead — see [Strategies](/trading/strategies).

# Data Functions

All functions read public on-chain data; holdings and swap history are visible for any address. Full parameter and schema documentation: [Jupiter Data](/market-data/jupiter-data).

| Function                                         | Purpose                                                                                         | Returns                                                             |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `searchJupiterTokens(query)`                     | Resolve a name, symbol, or mint to tradeable tokens                                             | DataFrame: `ticker`, mint, price, mcap, volume, liquidity, holders  |
| `screenJupiterTokens(...)`                       | Discover tokens by trending/most-traded/organic-score/recent, with liquidity and volume filters | DataFrame: token metadata, price, `organic_score`, 24h change       |
| `getJupiterOHLCV(tokens, start, end, timeframe)` | Candles — daily, hourly, minute (minute limited to 20 days per request)                         | Dict of DataFrames keyed by token: OHLCV                            |
| `getJupiterPrice(tokens)`                        | Live price with 24h change and liquidity                                                        | Dict per token: price, `price_change_24h`, liquidity                |
| `getJupiterHoldings(wallet)`                     | Token balances for any Solana wallet, priced live                                               | DataFrame: token, amount, price, `usd_value`                        |
| `getJupiterTokenTrades(token, ...)`              | Recent swaps for a token across all Solana DEXes, with trading wallets                          | DataFrame: wallet, side, price, amount, `usd_value`, dex, `tx_hash` |
| `getJupiterTokenHolders(token)`                  | Top holders ranked by balance                                                                   | DataFrame: rank, wallet, amount, `pct_supply`                       |
| `getJupiterWalletTrades(wallet, ...)`            | Swap history for any wallet                                                                     | DataFrame: per-swap traded token, side, price, counter leg          |
| `screenJupiterWallets(...)`                      | Trader PnL leaderboard across Solana DEXes                                                      | DataFrame: rank, wallet, pnl, realized/unrealized, volume           |
| `getJupiterTokenTopTraders(token, ...)`          | Most active wallets in a token by volume                                                        | DataFrame: rank, wallet, tags, trade counts, buy/sell volume        |

`J:` tickers also work with the cross-asset functions `getOHLCV()`, `getLatestPrice()`, and `getLatestSnapshot()`.

# Notes

* Jupiter has no central order book — there is no bid/ask, only the aggregated live price. `getLatestSnapshot()` returns `last` only for `J:` tickers.
* Selling an entire position may leave a dust quantity from rounding; treat positions with `abs(market_value) < $0.10` as closed.
* Positions and balances read on-chain state that can lag a fill by a moment — allow for settlement delay before re-querying after a trade.

# Related

* [Jupiter Data](/market-data/jupiter-data) — full function reference
* [Strategies](/trading/strategies) — automated strategy execution
* [Supported Venues](/trading/supported-brokerages) — venue registry and `venue.*` functions
* [Trading Fees](/usage/fees) — includes the Jupiter fee schedule