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

# Get Perp Quote

> Get a non-binding quote for opening a perpetual position on a supported DEX (Gains Network, Lighter). Quotes do not authenticate the caller and are not used by the execution flow; they are purely informational and exposed to help clients pick a DEX, price, or slippage before building a real payload.

<Note>
  **Quotes are informational only.** Execution uses the `/2/perp/payloads/<action>` → `/2/perp/execute-v2` flow. Use the quote endpoint to preview fills, fees, and which DEX would route best; then call `/2/perp/payloads/create-order` to build the actual signed payload you submit.
</Note>

### Request Body

<ParamField body="user" type="string" required>
  Wallet address of the trader. Used to scope the quote (e.g., Lighter account lookup).

  <Note>
    **Quote is unauthenticated.** Unlike the payload endpoints, `/2/perp/quote` does **not** take a `signature` field — only `user` is required. The quote endpoint is purely informational; nothing is signed or executed.
  </Note>
</ParamField>

<ParamField body="baseToken" type="string" required>
  Base token address, symbol, or Mobula asset id (e.g., `ETH`, `0x...`).
</ParamField>

<ParamField body="quote" type="string" required>
  Quote token of the market. Semantics differ per DEX:

  * **Lighter** — pass the ERC-20 collateral symbol (`USDC`).
  * **Gains** — pass the synthetic quote (`USD`).

  When unsure, pass `marketId` (e.g. `gains-btc-usd`, `lighter-btc-usd`) — the field is derived server-side from the market.
</ParamField>

<ParamField body="leverage" type="number" required>
  Leverage multiplier (e.g., `10` for 10x).
</ParamField>

<ParamField body="long" type="boolean" required>
  `true` for long, `false` for short. String form (`"true"`/`"false"`) is also accepted.
</ParamField>

<ParamField body="reduceOnly" type="boolean" required>
  `true` if the order should only reduce an existing position (never increase exposure).
</ParamField>

<ParamField body="collateralAmount" type="number" required>
  Collateral to commit, denominated in the `quote` token units (e.g., `100` USDC).
</ParamField>

<ParamField body="orderType" type="string">
  One of `market`, `limit`, `stop_limit`. Default `market`.
</ParamField>

<ParamField body="openPrice" type="number">
  Trigger/limit price. Required for `limit` and `stop_limit`.
</ParamField>

<ParamField body="tp" type="number">
  Take-profit price. Must be directionally valid (above open for long, below for short).
</ParamField>

<ParamField body="sl" type="number">
  Stop-loss price. Must be directionally valid (below open for long, above for short).
</ParamField>

<ParamField body="amountRaw" type="number">
  Raw position size in base-token units. If omitted, derived from `collateralAmount * leverage`.
</ParamField>

<ParamField body="maxSlippageP" type="number">
  Max slippage in percent (e.g., `0.5` = 0.5%).
</ParamField>

<ParamField body="chainIds" type="string[]">
  Routing **hint**, not a strict filter. If the matching market is not deployed on any of the requested chains, the router falls back to a chain that hosts it (e.g. `chainIds: ['evm:42161']` for a Base-only market silently returns `chainId: 'evm:8453'`). Always trust the response `chainId`. Omit to search all supported chains.
</ParamField>

<ParamField body="dexes" type="string[]">
  Restrict routing to specific DEXs. Values: `gains`, `lighter`. Omit to consider all.
</ParamField>

<ParamField body="marginMode" type="number">
  `0` = cross, `1` = isolated. DEX-specific; ignored when not applicable.
</ParamField>

<ParamField body="referrer" type="string">
  Referrer wallet address for fee sharing.
</ParamField>

### Response

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="dex" type="string">`gains` or `lighter`.</ResponseField>
    <ResponseField name="marketId" type="string">Mobula market identifier (e.g., `lighter-btc-usd`).</ResponseField>
    <ResponseField name="chainId" type="string">Chain where the order would be executed (e.g., `evm:42161`, `lighter:301`).</ResponseField>

    <ResponseField name="payload" type="object">
      Informational payload structure for the matched DEX. **Not** the payload used for execution — to execute, call `/2/perp/payloads/create-order` with the same parameters.

      <Expandable title="Lighter payload">
        <ResponseField name="type" type="string">`lighter`</ResponseField>
        <ResponseField name="orderType" type="string">`market` | `limit` | `stop_limit`</ResponseField>
        <ResponseField name="tp" type="number">Take-profit price, if set.</ResponseField>
        <ResponseField name="sl" type="number">Stop-loss price, if set.</ResponseField>

        <ResponseField name="data" type="object">
          Lighter order parameters (`marketIndex`, `clientOrderIndex`, `baseAmount`, `maxSlippage`, `isAsk`, `reduceOnly`, `nonce`, `apiKeyIndex`, `idealPrice`, `leverage`, optional `marginMode`).
        </ResponseField>
      </Expandable>

      <Expandable title="EVM payload (Gains)">
        <ResponseField name="type" type="string">`evm`</ResponseField>
        <ResponseField name="orderType" type="string">`market` | `limit` | `stop_limit`</ResponseField>
        <ResponseField name="tp" type="number">Take-profit price, if set.</ResponseField>
        <ResponseField name="sl" type="number">Stop-loss price, if set.</ResponseField>

        <ResponseField name="data" type="object">
          EVM transaction fields: `to`, `callData`, optional `from`, `value`, `chainId`, `nonce`, `gas`, `gasPrice`, `maxFeePerGas`, `maxPriorityFeePerGas`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payloadStr" type="string">JSON-stringified `payload` — provided for parity with payload endpoints but not used by `/2/perp/execute-v2`.</ResponseField>
  </Expandable>
</ResponseField>

### Errors

| Status | When                    | `message`               |
| ------ | ----------------------- | ----------------------- |
| 400    | Zod validation failed   | `zod validation failed` |
| 500    | No DEX returned a quote | `could not find quote`  |

The `errors` field lists per-DEX failures, formatted as `"<dex> - <error>"`.


## OpenAPI

````yaml POST /2/perp/quote
openapi: 3.0.0
info:
  version: 1.0.0
  title: Mobula API
  description: >-
    Documentation of the Mobula API


    **Demo API**: The default server (demo-api.mobula.io) is a demo API with
    rate limits.

    For production use, please use api.mobula.io with an API key from
    https://admin.mobula.io
servers:
  - url: https://demo-api.mobula.io/api/
    description: Demo API (rate limited, for testing only)
  - url: https://api.mobula.io/api/
    description: Production API (requires API key)
security: []
tags:
  - name: V2 - Token
    description: Token details, price, security, ATH, and holder data
  - name: V2 - Market Data
    description: Market details, OHLCV history, and lighthouse metrics
  - name: V2 - Trades
    description: Token trades, enriched trades, and trade filters
  - name: V2 - Wallet
    description: Wallet positions, activity, trades, analysis, and labels
  - name: V2 - Assets
    description: Cross-chain asset details and price history
  - name: V2 - Swap
    description: Swap quoting and execution
  - name: V2 - Perps
    description: Perpetual futures quoting, execution, and positions
  - name: V2 - Bridge
    description: Cross-chain bridge quoting and intent status (Alpha Preview)
  - name: V2 - DeFi
    description: Bonding pools and pulse data
  - name: V2 - Search
    description: Universal fast search
  - name: V2 - Blockchains
    description: System metadata and chain listings
  - name: V1 - Market Data
    description: Market prices, history, sparklines, pairs, and multi-data
  - name: V1 - Wallet
    description: Wallet portfolio, transactions, history, and NFTs
  - name: V1 - Token
    description: First buyers
  - name: V1 - Trades
    description: Market trades by pair
  - name: V1 - Metadata
    description: Token metadata, categories, trendings, and news
  - name: V1 - Assets
    description: List all assets
  - name: V1 - Search
    description: Search for assets, tokens, and pairs
  - name: V1 - DeFi
    description: Bonding pool pulse data
  - name: V1 - Blockchains
    description: Blockchain listings, pairs, and stats
  - name: V1 - Webhooks
    description: Webhook management
  - name: V1 - Feed
    description: Custom feed creation
paths:
  /2/perp/quote:
    post:
      tags:
        - V2 - Perps
      summary: Get perp quote
      description: >-
        Get a non-binding quote for opening a perpetual position on a supported
        DEX (Gains Network, Lighter). Informational only — execution uses
        /2/perp/payloads/<action> → /2/perp/execute-v2.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: string
                  description: >-
                    Wallet address of the trader. Used to scope the quote (e.g.,
                    Lighter account lookup).
                baseToken:
                  type: string
                  description: Base token address, symbol, or Mobula asset id.
                quote:
                  type: string
                  description: Quote/collateral token (typically USDC).
                leverage:
                  type: number
                long:
                  anyOf:
                    - type: boolean
                    - type: string
                reduceOnly:
                  type: boolean
                collateralAmount:
                  type: number
                orderType:
                  type: string
                  enum:
                    - market
                    - limit
                    - stop_limit
                openPrice:
                  type: number
                tp:
                  type: number
                sl:
                  type: number
                amountRaw:
                  type: number
                maxSlippageP:
                  type: number
                chainIds:
                  type: array
                  items:
                    type: string
                dexes:
                  type: array
                  items:
                    type: string
                    enum:
                      - gains
                      - lighter
                marginMode:
                  type: number
                referrer:
                  type: string
              required:
                - user
                - baseToken
                - quote
                - leverage
                - long
                - reduceOnly
                - collateralAmount
      responses:
        '200':
          description: Perp quote response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      dex:
                        type: string
                      marketId:
                        type: string
                      chainId:
                        type: string
                      payload:
                        type: object
                        properties: {}
                      payloadStr:
                        type: string
                    required:
                      - dex
                      - marketId
                      - chainId
                      - payload
                      - payloadStr
                required:
                  - success
                  - data

````