Jupiter Orders API

openapi: 3.2.0
info:
  title: Jupiter Prediction Market Orders API
  version: 1.0.0
  description: Jupiter Prediction Market API Schema
servers:
- url: https://api.jup.ag/prediction/v1
  description: Jupiter Prediction Market API Endpoint
security:
- ApiKeyAuth: []
tags:
- name: Orders
paths:
  /orders:
    get:
      tags:
      - Orders
      summary: List orders
      description: Paginated list of orders registered onchain. Filter by `ownerPubkey` and paginate with `start` and `end`.
      parameters:
      - schema:
          type:
          - integer
          - 'null'
          minimum: 0
        required: false
        description: Pagination start index of the page to return.
        name: start
        in: query
      - schema:
          type:
          - integer
          - 'null'
          minimum: 0
        required: false
        description: Pagination end index of the page to return.
        name: end
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        description: Filter orders by owner wallet public key.
        name: ownerPubkey
        in: query
      responses:
        '200':
          description: List of all orders registered on-chain
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  pagination:
                    type: object
                    properties:
                      start:
                        type: integer
                        minimum: 0
                      end:
                        type: integer
                        minimum: 0
                      total:
                        type: integer
                        minimum: 0
                      hasNext:
                        type: boolean
                    required:
                    - start
                    - end
                    - total
                    - hasNext
                required:
                - data
                - pagination
        '400':
          description: Failed to fetch orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getOrders
      x-operation-id-source: derived
    post:
      tags:
      - Orders
      summary: Create order
      description: 'Build an unsigned transaction that buys or sells YES or NO contracts on a market. Send exactly one quantity field: `contractsMicro` (1,000,000 = 1 contract), `contractsDecimal`, or the legacy whole-number `contracts`. Sign the returned transaction and submit it to `POST /execute` together with the `execution.context` object, unchanged.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Unsigned transaction for creating an order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postOrders
      x-operation-id-source: derived
  /execute:
    post:
      tags:
      - Orders
      summary: Execute a signed order transaction
      description: Submit a signed order transaction for execution. Pass the base64 `signedTransaction` together with the `execution.context` object returned by the order build (`POST /orders`, or `DELETE /positions/{positionPubkey}` for a sell), unchanged. Jupiter Forecast (bisonfi) orders execute as an atomic swap through this endpoint and the transaction signature is returned on success.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteRequest'
      responses:
        '200':
          description: Execution result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteResponse'
        '400':
          description: Execution failed or invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postExecute
      x-operation-id-source: derived
  /orders/{orderPubkey}:
    get:
      tags:
      - Orders
      summary: Get order
      description: 'One order by its account public key: market, side, size, status and timestamps.'
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Order account public key
        required: true
        description: Order account public key
        name: orderPubkey
        in: path
      responses:
        '200':
          description: Order data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Failed to fetch order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getOrdersByOrderPubkey
      x-operation-id-source: derived
  /orders/status/{orderPubkey}:
    get:
      tags:
      - Orders
      summary: Get order status
      description: Latest status of an order with its event history. Poll it after `POST /execute` to follow the fill.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Order account public key
        required: true
        description: Order account public key
        name: orderPubkey
        in: path
      responses:
        '200':
          description: Latest status for an order with event history
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderPubkey:
                    type: string
                  status:
                    type: string
                  latestEventType:
                    type: string
                  latestSignature:
                    type: string
                  externalOrderId:
                    type: string
                  orderId:
                    type: string
                  history:
                    type: array
                    items:
                      type: object
                      properties:
                        eventType:
                          type: string
                        status:
                          type: string
                        rawStatus:
                          type: string
                        timestamp:
                          type: integer
                        signature:
                          type: string
                        externalOrderId:
                          type: string
                        orderId:
                          type: string
                      required:
                      - eventType
                      - status
                      - rawStatus
                      - timestamp
                      - signature
                      - externalOrderId
                      - orderId
                required:
                - orderPubkey
                - status
                - latestEventType
                - latestSignature
                - externalOrderId
                - orderId
                - history
        '400':
          description: Failed to fetch order status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order history not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getOrdersStatusByOrderPubkey
      x-operation-id-source: derived
components:
  schemas:
    ExecuteResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - Success
          - Failed
          description: Transaction execution result.
        signature:
          type:
          - string
          - 'null'
          description: Transaction signature (base58) when execution succeeds.
        error:
          type:
          - string
          - 'null'
          description: Error message if the transaction failed, or `null` on success.
        requestId:
          type: string
          description: Echoed from the request when provided.
      required:
      - status
    CreateOrderResponse:
      type: object
      properties:
        transaction:
          type:
          - string
          - 'null'
          description: Base64 encoded transaction
        txMeta:
          type:
          - object
          - 'null'
          properties:
            blockhash:
              type: string
            lastValidBlockHeight:
              type: integer
              minimum: 0
          required:
          - blockhash
          - lastValidBlockHeight
          description: Transaction metadata
        externalOrderId:
          type:
          - string
          - 'null'
        requiredSigners:
          type: array
          items:
            type: string
          description: Public keys that must sign the returned transaction
        execution:
          $ref: '#/components/schemas/Execution'
        executionModel:
          type:
          - string
          - 'null'
          description: Execution model for the order. `atomic_swap` for Jupiter Forecast (bisonfi) orders, which execute as a single atomic swap through `POST /execute`. `null` for keeper-filled prediction orders.
        settlement:
          type:
          - string
          - 'null'
          description: Settlement mode. `auto` for Jupiter Forecast orders, which settle automatically. `null` for keeper-filled prediction orders.
        jupiterSwapRequestId:
          type:
          - string
          - 'null'
          description: Jupiter swap request id when the order executes as a swap (Jupiter Forecast). `null` otherwise.
        order:
          type: object
          properties:
            orderPubkey:
              type:
              - string
              - 'null'
              description: Order account public key
            orderAtaPubkey:
              type:
              - string
              - 'null'
              description: Order escrow token account
            userPubkey:
              type: string
              description: Order owner public key
            marketId:
              type: string
              description: Associated market identifier
            marketIdHash:
              type: string
              description: Hashed market identifier used for on-chain PDAs
            positionPubkey:
              type: string
              description: Position PDA used for the order
            isBuy:
              type: boolean
              description: True when the order increases exposure
            isYes:
              type: boolean
              description: True when the order is on the YES side
            contracts:
              type: string
              description: Legacy whole-contract quantity. Use contractsMicro or contractsDecimal for the exact fractional quantity.
            contractsMicro:
              type: string
              description: Contracts in micro-contract units (u64 as string, 1000000 = 1 contract)
            contractsDecimal:
              type: string
              description: Contracts as a decimal string
            newContracts:
              type: string
              description: Position contracts after executing the order (legacy whole-contract quantity)
            newContractsMicro:
              type: string
              description: Position contracts after the order, in micro-contract units
            newContractsDecimal:
              type: string
              description: Position contracts after the order, as a decimal string
            maxBuyPriceUsd:
              type:
              - string
              - 'null'
              description: Max fill price for buys (micro USD)
            minSellPriceUsd:
              type:
              - string
              - 'null'
              description: Min fill price for sells (micro USD)
            externalOrderId:
              type:
              - string
              - 'null'
              description: Client provided order identifier
            orderCostUsd:
              type: string
              description: Notional for this order in micro USD
            newAvgPriceUsd:
              type: string
              description: Average position entry price after the order
            newSizeUsd:
              type: string
              description: Total position cost basis after the order
            newPayoutUsd:
              type: string
              description: Position max payout after the order
            estimatedProtocolFeeUsd:
              type: string
              description: Estimated protocol fee (micro USD)
            estimatedVenueFeeUsd:
              type: string
              description: Estimated venue fee (micro USD)
            estimatedTotalFeeUsd:
              type: string
              description: Estimated total fees applied (micro USD)
            payoutUsd:
              type: string
              description: Position max payout for this order (micro USD)
            slippageBps:
              type: integer
              minimum: 0
              description: Estimated slippage for this order, in basis points (0 = none, 250 = 2.5%). For a Polymarket buy this is the estimated price impact from sweeping orderbook levels; for a sell it is the max allowed slippage from best bid to the protected sell floor. Treat it as a quote signal, not a guaranteed loss.
            maxSlippageBps:
              type:
              - integer
              - 'null'
              minimum: 0
              description: Maximum slippage allowed for this order, in basis points
          required:
          - orderPubkey
          - orderAtaPubkey
          - userPubkey
          - marketId
          - marketIdHash
          - positionPubkey
          - isBuy
          - isYes
          - contracts
          - newContracts
          - maxBuyPriceUsd
          - minSellPriceUsd
          - externalOrderId
          - orderCostUsd
          - newAvgPriceUsd
          - newSizeUsd
          - newPayoutUsd
          - estimatedProtocolFeeUsd
          - estimatedVenueFeeUsd
          - estimatedTotalFeeUsd
      required:
      - transaction
      - txMeta
      - externalOrderId
      - order
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - invalid_request_error
          - authentication_error
          - permission_error
          - idempotency_error
          - rate_limit_error
          - api_error
        message:
          type: string
        code:
          type: string
        param:
          type: string
        request_id:
          type: string
        doc_url:
          type: string
      required:
      - type
      - message
      - request_id
    Execution:
      type: object
      description: Execution details returned with an order build. Sign the build's `transaction`, then pass `context` unchanged to `POST /execute`.
      properties:
        endpoint:
          type: string
          description: Relative execute path. Resolves to `https://api.jup.ag/prediction/v1/execute`.
          example: /api/v1/execute
        context:
          type: object
          additionalProperties: true
          description: Opaque execution context. Pass this object unchanged to `POST /execute`. Includes a `type` field (`create_order` for keeper-filled orders, `bisonfi_swap` for Jupiter Forecast orders).
      required:
      - endpoint
      - context
    EventMetadata:
      type: object
      properties:
        eventId:
          type: string
        title:
          type: string
        subtitle:
          type: string
        slug:
          type: string
        series:
          type: string
        closeTime:
          type: string
          description: ISO 8601 formatted close time
        imageUrl:
          type: string
          format: uri
        isLive:
          type: boolean
      required:
      - eventId
    MarketMetadata:
      type: object
      properties:
        marketId:
          type: string
        eventId:
          type: string
        title:
          type: string
        subtitle:
          type: string
        description:
          type: string
        provider:
          type: string
        status:
          type: string
        result:
          type:
          - string
          - 'null'
        closeTime:
          type: number
        openTime:
          type: number
        isTeamMarket:
          type: boolean
        marketOptions:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              buyYes:
                type: boolean
        rulesPrimary:
          type: string
        rulesSecondary:
          type: string
      required:
      - marketId
    Order:
      type: object
      properties:
        pubkey:
          type: string
          description: Order account public key
        owner:
          type: string
          description: Order owner public key
        ownerPubkey:
          type: string
          description: Order owner public key (alias of owner, use ownerPubkey when available)
        market:
          type: string
          description: Associated market public key
        marketId:
          type: string
          description: External market identifier used to derive the PDA
        marketIdHash:
          type: string
          description: Hashed market identifier used for on-chain PDAs
        eventId:
          type: string
          description: External event identifier
        position:
          type: string
          description: Associated position public key
        status:
          type: string
          enum:
          - pending
          - filled
          - failed
          description: Current order status
        isYes:
          type: boolean
          description: True when order is for the YES side
        isBuy:
          type: boolean
          description: True when order is a buy order
        createdAt:
          type: integer
          description: Unix timestamp (seconds) when the order was created
        updatedAt:
          type: integer
          description: Unix timestamp (seconds) when the order last changed on-chain
        contracts:
          type: string
          description: Number of contracts (u64 as string)
        maxFillPriceUsd:
          type: string
          description: Maximum fill price in micro USD (u64 as string)
        maxBuyPriceUsd:
          type:
          - string
          - 'null'
          description: Buyer-specified max fill price (micro USD)
        minSellPriceUsd:
          type:
          - string
          - 'null'
          description: Seller-specified min fill price (micro USD)
        filledAt:
          type: integer
          description: Unix timestamp (seconds) when the order was filled (0 when pending)
        filledContracts:
          type: string
          description: Number of filled contracts (u64 as string)
        avgFillPriceUsd:
          type: string
          description: Average fill price in micro USD (u64 as string)
        settled:
          type: boolean
          description: Whether the order has been settled on-chain
        orderId:
          type: string
          description: External order identifier from the venue
        sizeUsd:
          type: string
          description: Order notional in micro USD (u128 as string)
        eventMetadata:
          $ref: '#/components/schemas/EventMetadata'
        marketMetadata:
          allOf:
          - $ref: '#/components/schemas/MarketMetadata'
          - properties:
              marketId:
                type: string
              eventId:
                type: string
              title:
                type: string
              status:
                type: string
              result:
                type: string
              closeTime:
                type: number
              openTime:
                type: number
              isTeamMarket:
                type: boolean
        externalOrderId:
          type: string
          description: Client-provided order identifier
        bump:
          type: integer
          minimum: 0
      required:
      - pubkey
      - owner
      - ownerPubkey
      - market
      - marketId
      - marketIdHash
      - eventId
      - position
      - status
      - isYes
      - isBuy
      - createdAt
      - updatedAt
      - contracts
      - maxFillPriceUsd
      - maxBuyPriceUsd
      - minSellPriceUsd
      - filledAt
      - filledContracts
      - avgFillPriceUsd
      - settled
      - orderId
      - sizeUsd
      - eventMetadata
      - marketMetadata
      - externalOrderId
      - bump
    CreateOrderRequest:
      type: object
      properties:
        ownerPubkey:
          type: string
          description: Order owner public key
        marketId:
          type: string
          minLength: 1
          description: Hashed or canonical market ID for buys
        positionPubkey:
          type: string
          minLength: 32
          description: Required for sells
        isYes:
          type: boolean
          description: '`true` to trade YES contracts, `false` for NO.'
        isBuy:
          type: boolean
          description: '`true` to buy contracts, `false` to sell.'
        contracts:
          anyOf:
          - type: string
          - type: number
          description: Legacy whole-contract sell quantity (only when `isBuy` is `false`). Cannot express fractions; prefer contractsMicro or contractsDecimal. Provide only one of contracts, contractsMicro, or contractsDecimal.
        contractsMicro:
          anyOf:
          - type: string
          - type: number
          description: Exact sell quantity in micro-contract units (1000000 = 1 contract). Provide only one of contracts, contractsMicro, or contractsDecimal.
        contractsDecimal:
          anyOf:
          - type: string
          - type: number
          description: Exact sell quantity as a decimal (e.g. 5.777773). Provide only one of contracts, contractsMicro, or contractsDecimal.
        depositAmount:
          anyOf:
          - type: string
          - type: number
          description: Amount must conform to the token decimals used by the token mint in `depositMint`
        depositMint:
          type: string
          default: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          description: Mint address for the deposit token
      required:
      - isBuy
    ExecuteRequest:
      type: object
      properties:
        signedTransaction:
          type: string
          description: Base64-encoded signed transaction from the order build.
        context:
          type: object
          additionalProperties: true
          description: Optional. The `execution.context` object from the order build, passed unchanged. Validated against the signed transaction when present. For a Forecast swap it carries `jupiterSwapRequestId` and `ownerPubkey`.
        requestId:
          type: string
          description: Optional client correlation ID, echoed back in the response.
      required:
      - signedTransaction
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Get API key via https://developers.jup.ag/portal
x-provenance:
  method: harvested
  publisher: Jupiter
  source: https://developers.jup.ag/docs/openapi-spec/prediction/prediction.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)