> ## 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.

# Perp account

> The live positions and resting orders of a wallet, one row per enabled venue (or for the venue
asked), read from the chain at every call.

- A venue whose chain read failed is **missing** from `accounts`; it is not reported as
  `registered: false`.
- `orders` lists resting orders only (limit, take profit, stop loss). A market request or order
  still waiting for the keeper is not listed; its address is `detail.request` in the
  `/perp/instructions` response, and `cancel` accepts it.
- If the order scan fails, `orders` is empty without an error.


Guide: [Perps](/router/perps#execution-is-asynchronous).


## OpenAPI

````yaml perp.openapi.yaml GET /perp/account
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/account:
    get:
      tags:
        - account
      summary: Positions and orders of a wallet
      description: >
        The live positions and resting orders of a wallet, one row per enabled
        venue (or for the venue

        asked), read from the chain at every call.


        - A venue whose chain read failed is **missing** from `accounts`; it is
        not reported as
          `registered: false`.
        - `orders` lists resting orders only (limit, take profit, stop loss). A
        market request or order
          still waiting for the keeper is not listed; its address is `detail.request` in the
          `/perp/instructions` response, and `cancel` accepts it.
        - If the order scan fails, `orders` is empty without an error.
      operationId: getPerpAccount
      parameters:
        - name: user
          in: query
          required: true
          description: Wallet address (base58)
          schema:
            type: string
            example: bJx6noQaPDTCQ2vxn2dMX1nYbTKhgprcj3bfAvYemky
        - name: venue
          in: query
          description: >-
            Only this venue. Aliases `jup`, `gmsol` and `gm` are accepted. Omit
            for every enabled venue
          schema:
            type: string
            enum:
              - jupiter
              - gmtrade
      responses:
        '200':
          description: One row per venue read. With no venue enabled, `accounts` is empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
              examples:
                gmtrade:
                  summary: A GMTrade short with two limits and a take profit
                  value:
                    quoteId: 94c3676a0000000f
                    user: bJx6noQaPDTCQ2vxn2dMX1nYbTKhgprcj3bfAvYemky
                    accounts:
                      - venue: jupiter
                        registered: true
                        collateralUsdE6: null
                        withdrawableUsdE6: null
                        positions: []
                        orders: []
                      - venue: gmtrade
                        registered: true
                        collateralUsdE6: null
                        withdrawableUsdE6: null
                        positions:
                          - marketId: gmtrade:BTC-USDC-USDC-PERP
                            side: short
                            account: 27stKrvjdgVWA2gGfjxhznUwsEDHSmwpbPB5toRsXXqV
                            sizeUsdE6: 41402640197
                            collateralUsdE6: null
                            entryPriceE6: 79036932246
                        orders:
                          - marketId: gmtrade:BTC-USDC-USDC-PERP
                            orderId: 3Wz7PMY9NDFnMyXwjXG4bC4iojvTeHdyGfqnZ8DPnpVo
                            kind: limit
                            triggerPriceE6: 87500000000
                            sizeUsdE6: 899924665
                          - marketId: gmtrade:BTC-USDC-USDC-PERP
                            orderId: 8JcKwkiRezTTFFjqyMrD7iDSKJ4oxf4JCzWPoSjGP4ES
                            kind: limit
                            triggerPriceE6: 88500000000
                            sizeUsdE6: 1049883644
                          - marketId: gmtrade:BTC-USDC-USDC-PERP
                            orderId: FnqEGuvafdixax7fHiSBnHHhkyoWdv8cjHQZQFeetMFg
                            kind: tp
                            triggerPriceE6: 77000000000
                            sizeUsdE6: 41402640197
                jupiter:
                  summary: A Jupiter short with a take profit closing all of it
                  value:
                    quoteId: 94c3676a00000013
                    user: 3yrYgLhLRa9G2tsmMHecPXk2iY1Ks1rhsLEeYEbasGif
                    accounts:
                      - venue: jupiter
                        registered: true
                        collateralUsdE6: null
                        withdrawableUsdE6: null
                        positions:
                          - marketId: jupiter:SOL-PERP
                            side: short
                            account: EkMmjYJi93EDayRAGNHCuJon2Xi7qq9NFbarSSEKaK75
                            sizeUsdE6: 4736924232
                            collateralUsdE6: 55357313
                            entryPriceE6: 117475545
                        orders:
                          - marketId: jupiter:SOL-PERP
                            orderId: Y6V9Me3DFkeQHst32eqcVNbDN3HXFPJNkGXtwzPif6o
                            kind: tp
                            triggerPriceE6: 115500000
                            sizeUsdE6: null
        '400':
          description: '`user` is missing or not an address, or `venue` is not a perp venue'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing:
                  summary: No user
                  value:
                    error: bad_request
                    reason: user is required
                    quoteId: 23e14e0100004500
                notAddress:
                  summary: Not base58
                  value:
                    error: bad_request
                    reason: user is not a base58 address
                    quoteId: 23e14e0100004501
        '422':
          $ref: '#/components/responses/VenueDisabled'
        '503':
          $ref: '#/components/responses/NotReady'
components:
  schemas:
    AccountResponse:
      type: object
      properties:
        quoteId:
          type: string
        user:
          type: string
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/VenueAccount'
    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
    VenueAccount:
      type: object
      properties:
        venue:
          type: string
          enum:
            - jupiter
            - gmtrade
        registered:
          type: boolean
          description: >-
            GMTrade: the wallet's GMTrade user account exists (the first order
            creates it in the same transaction). Jupiter: always true
        collateralUsdE6:
          type:
            - integer
            - 'null'
          format: int64
          description: >-
            Reserved for a venue-level collateral account; null on both venues
            (collateral lives in each position)
        withdrawableUsdE6:
          type:
            - integer
            - 'null'
          format: int64
          description: Reserved; null on both venues
        positions:
          type: array
          items:
            $ref: '#/components/schemas/Position'
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    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
    Position:
      type: object
      properties:
        marketId:
          type: string
        side:
          type: string
          enum:
            - long
            - short
        account:
          type: string
          description: The position account
        sizeUsdE6:
          type: integer
          format: int64
          description: Position size (notional) in micro-USD
        collateralUsdE6:
          type:
            - integer
            - 'null'
          format: int64
          description: 'Jupiter: the position''s collateral in micro-USD. GMTrade: null'
        entryPriceE6:
          type: integer
          format: int64
          description: Average entry price × 10^6
    Order:
      type: object
      properties:
        marketId:
          type: string
        orderId:
          type: string
          description: >-
            The request/order address; pass it as `orderId` to `cancel` or
            `update`
        kind:
          type: string
          enum:
            - limit
            - tp
            - sl
          description: '`limit` opens at the trigger; `tp` and `sl` reduce a position'
        triggerPriceE6:
          type:
            - integer
            - 'null'
          format: int64
        sizeUsdE6:
          type:
            - integer
            - 'null'
          format: int64
          description: >-
            Size the order adds or closes; null when it closes the whole
            position
  responses:
    VenueDisabled:
      description: The venue asked is not enabled on this router (`ROUTER_PERP`)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: venue_disabled
            reason: jupiter is not enabled on this host (ROUTER_PERP)
            quoteId: 23e14e01000044f9
    NotReady:
      description: >-
        The router is not ready (cold start, stream down, swap config not read);
        `reasons` says why
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotReady'

````

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