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

# Quote a perp open

> What opening a position would take, at the live mark: the collateral in the collateral mint,
the notional, the venue fee estimate and an estimated liquidation price. Nothing is built and
nothing is reserved.

With `triggerPriceE6` the quote is that of a **limit open** (GMTrade only; Jupiter answers
`422 venue_form`): same fields, collateral converted at today's mark (it is deposited now), and
the liquidation estimated at the trigger price. A long limit must sit below the mark and a
short limit above it.

When `fundingMint` is another token than the collateral, the exact-out funding route is quoted
too (`funding`), with a `routeTicket` you can pass to `/perp/instructions` to build on that
route.

The quote of a market open and the `quote` that `/perp/instructions` returns for the same
request are computed by the same function.


Guide: [Perps](/router/perps). `estLiquidationE6` is an estimate with a 0.6% maintenance margin, not the venue's rule.


## OpenAPI

````yaml perp.openapi.yaml POST /perp/quote
openapi: 3.1.0
info:
  title: Raze Router Perps API
  version: 1.0.0
  description: >
    Perpetual futures on Solana through the router: live markets, quotes,
    unsigned

    transactions and the live state of a wallet, on **Jupiter Perps**
    (`jupiter`) and **GMTrade**

    (gmsol / GMX-Solana, `gmtrade`).


    **The router never signs and never sends.** `POST /perp/instructions`
    returns the instructions

    and, on request, the serialized unsigned transaction; your backend has the
    wallet sign it and

    broadcasts it.


    **One operation, one transaction.** The collateral deposit travels in the
    same transaction as the

    order, and when the wallet pays with another token (`fundingMint`) an
    exact-out swap route into the

    collateral mint is placed in front of the venue instruction, in that same
    transaction.


    **Execution is asynchronous on both venues.** The transaction creates a
    request (Jupiter) or an

    order (GMTrade); the venue's keeper executes it afterwards in its own
    transaction, at its own

    oracle price. Watch `GET /perp/account` (or the chain) to see the fill.


    **Conventions, everywhere:**

    - Perps are off until you enable them: `ROUTER_PERP=jupiter,gmtrade` (or
    `all`) in the router's
      environment. A venue that is off answers `422 venue_disabled`.
    - Market ids are `<venue>:<SYMBOL>-PERP`, e.g. `jupiter:SOL-PERP`,
    `gmtrade:SOL-WSOL-USDC-PERP`.
      Case-insensitive; `-PERP` is optional; `jup:`, `gmsol:` and `gm:` are accepted as aliases.
    - USD amounts are integers in micro-USD: fields ending in `Usd` (requests)
    and `UsdE6`
      (responses), so `10000000` is $10.
    - Prices are integers, USD per whole token × 10^6 (`priceE6`,
    `triggerPriceE6`).

    - Leverage and shares are basis points: `leverageBps` 20000 = 2x, `closeBps`
    10000 = all.

    - Token amounts (`collateralAmount`, `amountIn`…) are raw base units of the
    mint.

    - Amounts and prices are JSON integers (send them as numbers, not strings).
    A response field
      that does not apply is omitted, except in `/perp/account` where an unknown value is `null`.
    - Times are Unix **seconds**.

    - Failure: `{"error": "<label>", "reason": "<text>", "quoteId": "<id>"}`.
    The status says whose
      fault it is: 400 the request, 409 re-quote, 422 a named decline, 503 the router or the chain.
      A body over 256 KiB is refused with 413; an unknown route answers 404 `not_found`.

    **On `https://router.raze.bot` perps are not enabled:** `GET /perp/markets`
    lists no venue and

    every operation answers `422 venue_disabled`. They work on a router of your
    own with

    `ROUTER_PERP` set.


    **No authentication.** A router you run yourself listens on loopback
    (`ROUTER_LISTEN`, default

    `127.0.0.1:4700`) and trusts its caller; put your own auth in front of it if
    you expose it.
servers:
  - url: https://router.raze.bot
    description: Raze's public router (perps not enabled)
  - url: http://127.0.0.1:4700
    description: Your own router (default ROUTER_LISTEN)
security: []
tags:
  - name: markets
    description: Live perp markets per venue
  - name: trading
    description: Quotes and unsigned transactions for every perp operation
  - name: account
    description: Live positions and resting orders of a wallet
paths:
  /perp/quote:
    post:
      tags:
        - trading
      summary: Quote an open
      description: >
        What opening a position would take, at the live mark: the collateral in
        the collateral mint,

        the notional, the venue fee estimate and an estimated liquidation price.
        Nothing is built and

        nothing is reserved.


        With `triggerPriceE6` the quote is that of a **limit open** (GMTrade
        only; Jupiter answers

        `422 venue_form`): same fields, collateral converted at today's mark (it
        is deposited now), and

        the liquidation estimated at the trigger price. A long limit must sit
        below the mark and a

        short limit above it.


        When `fundingMint` is another token than the collateral, the exact-out
        funding route is quoted

        too (`funding`), with a `routeTicket` you can pass to
        `/perp/instructions` to build on that

        route.


        The quote of a market open and the `quote` that `/perp/instructions`
        returns for the same

        request are computed by the same function.
      operationId: quotePerp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
            examples:
              jupiterLong:
                summary: Jupiter, $25 long SOL at 3x, collateral already held
                value:
                  marketId: jupiter:SOL-PERP
                  side: long
                  collateralUsd: 25000000
                  leverageBps: 30000
              jupiterShort:
                summary: Jupiter, $100 short BTC at 5x, 0.3 % slippage
                value:
                  marketId: jupiter:BTC-PERP
                  side: short
                  collateralUsd: 100000000
                  leverageBps: 50000
                  slippageBps: 30
              gmtradeLimit:
                summary: GMTrade, limit short SOL at $130
                value:
                  marketId: gmtrade:SOL-USDC-USDC-PERP
                  side: short
                  collateralUsd: 25000000
                  leverageBps: 50000
                  triggerPriceE6: 130000000
              paidInSol:
                summary: Jupiter, paid in native SOL (wrapped in the transaction)
                value:
                  marketId: jupiter:SOL-PERP
                  side: long
                  collateralUsd: 25000000
                  leverageBps: 30000
                  fundingMint: SOL
      responses:
        '200':
          description: The quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
              examples:
                jupiterLong:
                  summary: Jupiter long SOL, collateral held
                  value:
                    quoteId: 94c3676a00000002
                    marketId: jupiter:SOL-PERP
                    venue: jupiter
                    side: long
                    quote:
                      mark:
                        priceE6: 117469991
                        slot: 452411041
                        publishTime: 1790890823
                        source: doves
                      collateralMint: So11111111111111111111111111111111111111112
                      collateralAmount: 212820310
                      collateralUsdE6: 25000000
                      notionalUsdE6: 75000000
                      leverageBps: 30000
                      initialMarginUsdE6: 25000000
                      feeUsdE6: 45000
                      estLiquidationE6: 79022062
                    fundingMode: held
                    timeTaken: 0.000206842
                jupiterShort:
                  summary: Jupiter short BTC, USDC collateral
                  value:
                    quoteId: 94c3676a00000003
                    marketId: jupiter:BTC-PERP
                    venue: jupiter
                    side: short
                    quote:
                      mark:
                        priceE6: 84479708630
                        slot: 452411041
                        publishTime: 1790890823
                        source: doves
                      collateralMint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                      collateralAmount: 100000000
                      collateralUsdE6: 100000000
                      notionalUsdE6: 500000000
                      leverageBps: 50000
                      initialMarginUsdE6: 100000000
                      feeUsdE6: 300000
                      estLiquidationE6: 100868772104
                    fundingMode: held
                    timeTaken: 0.000280171
                gmtradeLimit:
                  summary: GMTrade limit short, liquidation estimated at the trigger
                  value:
                    quoteId: 94c3676a00000008
                    marketId: gmtrade:SOL-USDC-USDC-PERP
                    venue: gmtrade
                    side: short
                    quote:
                      mark:
                        priceE6: 117611578
                        slot: 452410915
                        publishTime: 1790890742
                        source: chainlink
                      collateralMint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                      collateralAmount: 25000650
                      collateralUsdE6: 25000000
                      notionalUsdE6: 125000000
                      leverageBps: 50000
                      initialMarginUsdE6: 25000000
                      feeUsdE6: 0
                      estLiquidationE6: 155220000
                    fundingMode: held
                    timeTaken: 0.046765235
        '400':
          description: >-
            A field is missing or wrong, the market is unknown, or a limit sits
            on the wrong side of the mark
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingField:
                  summary: The body does not parse (no quoteId)
                  value:
                    error: bad_request
                    reason: missing field `leverageBps` at line 1 column 70
                badMarketId:
                  summary: Not a market id
                  value:
                    error: bad_request
                    reason: 'marketId: <venue>:<SYMBOL>-PERP'
                    quoteId: 23e14e01000044fb
                unknownMarket:
                  summary: >-
                    A symbol the venue does not list (GMTrade ETH needs its
                    pool, e.g. ETH-USDC-USDC)
                  value:
                    error: unknown_market
                    reason: unknown market
                    quoteId: 94c3676a0000000a
                wrongSide:
                  summary: A long limit above the mark
                  value:
                    error: bad_request
                    reason: 'bad request: a long limit must sit below the mark'
                    quoteId: 94c3676a0000000b
                leverage:
                  summary: Leverage below 1x
                  value:
                    error: bad_request
                    reason: 'bad request: leverage below 1x'
                    quoteId: 94c3676a0000000d
        '422':
          description: >-
            The venue is off, the venue cannot express this, or the funding
            route was declined
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                venueDisabled:
                  summary: Venue not in ROUTER_PERP
                  value:
                    error: venue_disabled
                    reason: jupiter is not enabled on this host (ROUTER_PERP)
                    quoteId: 23e14e01000044fc
                venueForm:
                  summary: Limit on Jupiter
                  value:
                    error: venue_form
                    reason: >-
                      not expressible on this venue: jupiter has no user-signed
                      limit increase: instantCreateLimitOrder also wants the
                      keeper
                    quoteId: 94c3676a00000006
                disabledMarket:
                  summary: A GMTrade market the venue has disabled
                  value:
                    error: venue_form
                    reason: >-
                      not expressible on this venue: the venue has disabled this
                      market
                    quoteId: 94c3676a0000000c
                noFundingRoute:
                  summary: No route from fundingMint into the collateral
                  value:
                    error: declined
                    reason: 'funding leg: no_route'
                    quoteId: 94c3676a00000005
        '503':
          $ref: '#/components/responses/StateUnavailable'
components:
  schemas:
    QuoteRequest:
      type: object
      required:
        - marketId
        - side
        - collateralUsd
        - leverageBps
      properties:
        marketId:
          type: string
          description: '`<venue>:<SYMBOL>-PERP`, from `/perp/markets`'
          example: jupiter:SOL-PERP
        side:
          type: string
          enum:
            - long
            - short
          description: '`buy` and `sell` are accepted too'
        collateralUsd:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Collateral in micro-USD (10000000 = $10). The notional is collateral
            × leverage
          example: 25000000
        leverageBps:
          type: integer
          format: int32
          minimum: 10000
          description: >-
            Leverage in bps (30000 = 3x). The router enforces only the 1x
            minimum; the venue's limits apply at execution
          example: 30000
        slippageBps:
          type: integer
          format: int32
          default: 50
          minimum: 0
          maximum: 9999
          description: >-
            Accepted price move from the mark at execution, and the funding
            route's slippage
        fundingMint:
          type: string
          description: >
            What the wallet pays with. Omitted or the collateral mint: the
            collateral already in the

            wallet's token account (`held`). `SOL` or `native`: native SOL,
            wrapped in the transaction

            when the collateral is wSOL (`native`), otherwise routed from SOL.
            Any other mint: an

            exact-out route into the collateral (`routed`). The wSOL mint
            address means wSOL already held.
        wallet:
          type: string
          description: Optional, only validated as an address
        triggerPriceE6:
          type: integer
          format: int64
          minimum: 1
          description: Quote a limit open at this price (GMTrade only)
    QuoteResponse:
      type: object
      required:
        - quoteId
        - marketId
        - venue
        - side
        - quote
        - fundingMode
        - timeTaken
      properties:
        quoteId:
          type: string
        marketId:
          type: string
          description: Canonical market id
        venue:
          type: string
          enum:
            - jupiter
            - gmtrade
        side:
          type: string
          enum:
            - long
            - short
        quote:
          $ref: '#/components/schemas/OpenQuote'
        fundingMode:
          type: string
          enum:
            - held
            - native
            - routed
          description: >-
            How the collateral reaches the venue: already in the wallet, native
            SOL wrapped in the transaction, or a swap route in the transaction
        funding:
          $ref: '#/components/schemas/Funding'
        timeTaken:
          type: number
          description: Seconds spent by the router
    Error:
      type: object
      required:
        - error
        - reason
      properties:
        error:
          type: string
          description: >
            The label. 400: `bad_request`, `unknown_market`, `request` (the
            order named cannot be acted

            on), `invalid_route_ticket`, `route_ticket_mismatch`. 404:
            `not_found`. 409:

            `route_expired`. 422: `venue_disabled`, `venue_form`, `no_position`,
            `size`, `layout`,

            `wire`, `declined`. 503: `missing_state`, `oracle`, `rpc`,
            `declined` (funding route accounts

            could not be fetched). 500: `internal`.
          enum:
            - bad_request
            - unknown_market
            - request
            - invalid_route_ticket
            - route_ticket_mismatch
            - not_found
            - route_expired
            - venue_disabled
            - venue_form
            - no_position
            - size
            - layout
            - wire
            - declined
            - missing_state
            - oracle
            - rpc
            - internal
        reason:
          type: string
          description: What exactly; free text for humans and logs
        quoteId:
          type: string
          description: >-
            Id of this call in the router's logs (16 hex). Absent when the body
            does not parse
          example: 94c3676a00000002
    OpenQuote:
      type: object
      required:
        - mark
        - collateralMint
        - collateralAmount
        - collateralUsdE6
        - notionalUsdE6
        - leverageBps
        - initialMarginUsdE6
        - feeUsdE6
      properties:
        mark:
          $ref: '#/components/schemas/Mark'
        collateralMint:
          type: string
          description: The mint deposited
        collateralAmount:
          type: integer
          format: int64
          description: >-
            Raw units of `collateralMint` the order deposits (USD converted at
            the collateral token's price; USDC is 1:1 on Jupiter and at its
            Chainlink price on GMTrade)
        collateralUsdE6:
          type: integer
          format: int64
        notionalUsdE6:
          type: integer
          format: int64
          description: Position size added, collateral × leverage
        leverageBps:
          type: integer
          format: int32
        initialMarginUsdE6:
          type: integer
          format: int64
          description: Equal to the collateral
        feeUsdE6:
          type: integer
          format: int64
          description: >-
            Opening fee estimate. Jupiter: the custody's open fee on the
            notional. GMTrade: always 0 (its fee depends on price impact and is
            not estimated)
        estLiquidationE6:
          type: integer
          format: int64
          description: >-
            Indicative liquidation price (isolated margin, 0.6 % maintenance),
            not the venue's rule. For a limit, computed at the trigger
        maxLeverageBps:
          type: integer
          description: Reserved; not emitted today
    Funding:
      type: object
      description: >-
        The exact-out swap route into the collateral mint, present only when
        `fundingMode` is `routed`
      required:
        - inputMint
        - outputMint
        - amountIn
        - amountOut
        - maxAmountIn
        - route
      properties:
        inputMint:
          type: string
          description: The mint the wallet pays with (wSOL for native SOL)
        outputMint:
          type: string
          description: The collateral mint
        amountIn:
          type: integer
          format: int64
          description: Expected input, raw units
        amountOut:
          type: integer
          format: int64
          description: >-
            Collateral delivered, raw units; the venue instruction deposits
            exactly this
        maxAmountIn:
          type: integer
          format: int64
          description: Most the route may take (slippage included)
        route:
          type: array
          items:
            $ref: '#/components/schemas/FundingHop'
        routeTicket:
          type: string
          description: >-
            `/perp/quote` only, when the router has `ROUTER_TICKET_SECRET`: pass
            it to `/perp/instructions` to build this route (valid
            `ROUTER_TICKET_TTL_S`, default 60 s)
    NotReady:
      type: object
      required:
        - error
        - reasons
      properties:
        error:
          type: string
          const: not_ready
        reasons:
          type: array
          items:
            type: string
          description: Every reason the router is not ready
        quoteId:
          type: string
    Mark:
      type: object
      description: The reference price of the market's index token
      required:
        - priceE6
        - slot
        - source
      properties:
        priceE6:
          type: integer
          format: int64
          description: USD per whole token × 10^6
          example: 117432055
        slot:
          type: integer
          format: int64
          description: Slot of the oracle account the price was read from
        publishTime:
          type: integer
          format: int64
          description: >-
            When the price was published, Unix seconds. On GMTrade the older of
            the report's signing and its landing
        source:
          type: string
          enum:
            - doves
            - chainlink
          description: >-
            `doves` (Jupiter's oracle) or `chainlink` (GMTrade's Chainlink Data
            Streams feed)
    FundingHop:
      type: object
      properties:
        dex:
          type: string
          description: Venue of the hop, as in the router's `/venues`
        pool:
          type: string
        inputMint:
          type: string
        outputMint:
          type: string
        inputAmount:
          type: integer
          format: int64
        outputAmount:
          type: integer
          format: int64
        priceBasis:
          type: string
          enum:
            - curve_exact
            - vault_reserves
            - bin_walk
            - tick_walk
            - template_replay
            - flat_fallback
            - ticket
        exact:
          type: string
          enum:
            - exact
            - bounded_below
            - approx
            - ticket
        feeBps:
          type: integer
        feeSource:
          type: string
          enum:
            - on_chain
            - default
            - ticket
  responses:
    StateUnavailable:
      description: >
        Ours, not yours: retry later. `not_ready` (the router is not ready, no
        blockhash for

        `serialize`, or the swap program is paused for a routed funding leg),
        `oracle` (the mark is

        stale: Doves older than 90 s, a GMTrade feed older than its heartbeat),
        `missing_state` (a venue

        account is not loaded yet), `rpc` (the wallet's accounts could not be
        read).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/NotReady'
          examples:
            oracle:
              summary: GMTrade feed past its heartbeat
              value:
                error: oracle
                reason: 'oracle: price feed older than the venue''s heartbeat'
                quoteId: 94c3676a00000009

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.