Token-Pair Endpoints

Overview

The token-pair endpoints accept a baseTokenMint instead of an explicit offerPublicKey. The server automatically selects the best matching liquidity pool (offer) — you never need to query offers directly.

For new integrations, always use these endpoints. The offerPublicKey endpoints (POST /positions/open) exist for advanced use cases but require you to discover and manage offer addresses manually.

POST /api/v1/positions/quote-by-token

Get a price preview without building a transaction. Use this to display expected entry price, slippage, and fees before asking the user to confirm.

Request:

{
  "baseTokenMint": "So11111111111111111111111111111111111111112",
  "userPublicKey": "GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v",
  "collateralAmount": "1000000000",
  "leverage": 3,
  "side": "LONG",
  "quoteTokenMint": "So11111111111111111111111111111111111111112",
  "slippageBps": 50
}

Field	Type	Required	Description
`baseTokenMint`	string	Yes	Token mint you want to go long/short on (base58)
`userPublicKey`	string	Yes	User's wallet address (base58)
`collateralAmount`	string	Yes	Collateral in the quote token's smallest units (lamports for SOL)
`leverage`	number	Yes	Multiplier between 1.1 and 100
`side`	string	Yes	`"LONG"` or `"SHORT"`
`quoteTokenMint`	string	No	Quote token (default: WSOL for LONG, USDC for SHORT)
`slippageBps`	number	No	Slippage tolerance in bps (default: 50, max: 1000)

Response: Returns a SwapQuote object:

{
  "inAmount": "1000000000",
  "outAmount": "2950000000",
  "priceImpactPct": "0.12",
  "otherAmountThreshold": "2920500000",
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "So11111111111111111111111111111111111111112",
  "slippageBps": 50
}

POST /api/v1/positions/open-by-token

Build an unsigned Solana transaction to open a leveraged position. Takes the same request shape as quote-by-token.

Request: Identical to quote-by-token above.

Response:

{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAkP...",
  "positionAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "lastValidBlockHeight": 285432100,
  "quote": { "outAmount": "9950000000", "priceImpactPct": 0.12, "slippageBps": 50 }
}

Deserialise with VersionedTransaction.deserialize(bs58.decode(response.transaction)), sign with the user's wallet, and submit.

How Offer Matching Works

When you call open-by-token, the server:

Queries active offers for the requested token pair and side
Filters by available liquidity (must cover collateralAmount × (leverage - 1))
Sorts by best terms (highest leverage limit, lowest utilization)
Selects the top offer and builds the transaction against it

If no matching offer exists, the server returns 404 NO_OFFER_FOR_TOKEN.

Supported Sides

Side	Collateral Token	What Happens
`LONG`	WSOL (default) or USDC	Protocol borrows SOL/USDC, swaps into the target token. Profit when price rises.
`SHORT`	USDC	Protocol borrows the volatile token, swaps to USDC. Profit when price falls.

Short position support is currently in beta. Contact [email protected] for access.