Jupiter Positions API

openapi: 3.2.0
info:
  title: Jupiter Prediction Market Positions 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: Positions
paths:
  /positions:
    get:
      tags:
      - Positions
      summary: List positions
      description: Paginated list of onchain positions, each holding YES or NO contracts in one market. Filter by `ownerPubkey`, `marketPubkey`, `marketId` and `isYes`; paginate with `start` and `end`. USD values are in micro USD (1,000,000 = $1).
      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
          description: Position owner public key
        required: false
        description: Position owner public key
        name: ownerPubkey
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        description: Filter by market account public key.
        name: marketPubkey
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        description: Filter by market id.
        name: marketId
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
          description: Filter by position side (true = YES, false = NO)
        required: false
        description: Filter by position side (true = YES, false = NO)
        name: isYes
        in: query
      responses:
        '200':
          description: List of on-chain positions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Position'
                  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 positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getPositions
      x-operation-id-source: derived
    delete:
      tags:
      - Positions
      summary: Close all positions
      description: Build one unsigned sell transaction per open position of a wallet, selling every contract. `minSellPriceSlippageBps` bounds the accepted sell price. Sign each transaction and submit it to `POST /execute`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseAllPositionsRequest'
      responses:
        '200':
          description: Unsigned transactions that sell all contracts across every open position for the user
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/CreateOrderResponse'
                      - $ref: '#/components/schemas/ClaimPositionResponse'
                required:
                - data
        '400':
          description: Unable to build close positions transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: deletePositions
      x-operation-id-source: derived
  /positions/{positionPubkey}:
    get:
      tags:
      - Positions
      summary: Get position
      description: 'One position by its account public key: side, contracts held (`contractsMicro` and `contractsDecimal`), cost basis, mark price and unrealised P&L in micro USD.'
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Position account public key
        required: true
        description: Position account public key
        name: positionPubkey
        in: path
      responses:
        '200':
          description: Position data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
        '400':
          description: Failed to fetch position
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Position not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getPositionsByPositionPubkey
      x-operation-id-source: derived
    delete:
      tags:
      - Positions
      summary: Close position
      description: Build an unsigned transaction that sells every contract of one position before the market resolves. Sign it and submit it to `POST /execute` together with the `execution.context` object.
      parameters:
      - schema:
          type: string
          minLength: 32
          description: Position account public key
        required: true
        description: Position account public key
        name: positionPubkey
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClosePositionRequest'
      responses:
        '200':
          description: Unsigned transaction that sells all contracts for a position
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          description: Unable to build close position transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Position not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: deletePositionsByPositionPubkey
      x-operation-id-source: derived
  /positions/{positionPubkey}/claim:
    post:
      tags:
      - Positions
      summary: Claim position
      description: Build an unsigned transaction that claims the payout of a winning position after the market has resolved. Each winning contract pays out $1. Sign and send the returned transaction.
      parameters:
      - schema:
          type: string
          minLength: 32
          description: Position account public key
        required: true
        description: Position account public key
        name: positionPubkey
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimPositionRequest'
      responses:
        '200':
          description: Unsigned transaction to claim payout for a winning position
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimPositionResponse'
        '400':
          description: Unable to build claim payout transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Position not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postPositionsByPositionPubkeyClaim
      x-operation-id-source: derived
components:
  schemas:
    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
    Position:
      type: object
      properties:
        pubkey:
          type: string
          description: Position account public key
        owner:
          type: string
          description: Position owner public key
        ownerPubkey:
          type: string
          description: Position owner public key (alias of owner, prefer ownerPubkey going forward)
        market:
          type: string
          description: Deterministic market PDA derived from marketId
        marketId:
          type: string
          description: External market identifier (ticker)
        marketIdHash:
          type: string
          description: Hashed market identifier used for on-chain PDAs
        isYes:
          type: boolean
          description: True if this is a YES position
        contracts:
          type: string
          description: Legacy whole-contract quantity held. Use contractsMicro or contractsDecimal for the exact fractional quantity.
        contractsMicro:
          type: string
          description: Contracts held in micro-contract units (u64 as string, 1000000 = 1 contract)
        contractsDecimal:
          type: string
          description: Contracts held as a decimal string
        source:
          type: string
          description: Origin of the position (e.g. "program")
        maxSlippageBps:
          type: integer
          minimum: 0
          description: Maximum slippage recorded for the position, in basis points
        totalCostUsd:
          type: string
          description: Total cost basis in micro USD (u128 as string)
        sizeUsd:
          type: string
          description: Alias of total cost basis in micro USD (u128 as string)
        valueUsd:
          type:
          - string
          - 'null'
          description: Mark-to-market value in micro USD (u128 as string); null once market is closed
        avgPriceUsd:
          type: string
          description: Average entry price per contract in micro USD (u64 as string)
        markPriceUsd:
          type:
          - string
          - 'null'
          description: Current mark price per contract in micro USD (u64 as string); null once market is closed
        sellPriceUsd:
          type:
          - string
          - 'null'
          description: Current best exit price for this side (micro USD string), or null when unavailable
        pnlUsd:
          type:
          - string
          - 'null'
          description: Unrealized PnL in micro USD (i128 as string); null once market is closed
        pnlUsdPercent:
          type:
          - number
          - 'null'
          description: Unrealized PnL percentage relative to size; null once market is closed
        pnlUsdAfterFees:
          type:
          - string
          - 'null'
          description: Unrealized PnL after fees in micro USD (i128 as string); null once market is closed
        pnlUsdAfterFeesPercent:
          type:
          - number
          - 'null'
          description: Unrealized PnL after fees percentage relative to size; null once market is closed
        openOrders:
          type: integer
          minimum: 0
          description: Number of open orders
        feesPaidUsd:
          type: string
          description: Total fees paid in micro USD (u64 as string)
        realizedPnlUsd:
          type: number
          description: Realized PnL in micro USD (i64 as number)
        claimed:
          type: boolean
          description: Whether payout has been claimed
        claimedUsd:
          type: string
          description: Amount claimed in micro USD (u64 as string)
        openedAt:
          type: integer
          description: Unix timestamp when the position was opened
        updatedAt:
          type: integer
          description: Unix timestamp of the last position update
        claimableAt:
          type:
          - integer
          - 'null'
          description: Unix timestamp (seconds) when the position becomes claimable; null when unavailable
        payoutUsd:
          type: string
          description: Notional payout if position wins (contracts * $1)
        bump:
          type: integer
          minimum: 0
        eventId:
          type: string
          description: External event identifier if available
        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
        settlementDate:
          type:
          - integer
          - 'null'
          description: Unix timestamp (seconds) when the market settles; null when unavailable
        claimable:
          type: boolean
          description: True when the position qualifies for payout claim
      required:
      - pubkey
      - owner
      - ownerPubkey
      - market
      - marketId
      - marketIdHash
      - isYes
      - contracts
      - totalCostUsd
      - sizeUsd
      - valueUsd
      - avgPriceUsd
      - markPriceUsd
      - sellPriceUsd
      - pnlUsd
      - pnlUsdPercent
      - pnlUsdAfterFees
      - pnlUsdAfterFeesPercent
      - openOrders
      - feesPaidUsd
      - realizedPnlUsd
      - claimed
      - claimedUsd
      - openedAt
      - updatedAt
      - claimableAt
      - payoutUsd
      - bump
      - eventId
      - eventMetadata
      - marketMetadata
      - settlementDate
      - claimable
    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
    ClaimPositionRequest:
      type: object
      properties:
        ownerPubkey:
          type: string
          minLength: 32
          description: Position owner public key
    CloseAllPositionsRequest:
      type: object
      properties:
        ownerPubkey:
          type: string
          minLength: 32
          description: Position owner public key
        minSellPriceSlippageBps:
          type: number
          description: Slippage tolerance applied to each sell, in basis points. Required.
      required:
      - minSellPriceSlippageBps
    ClosePositionRequest:
      type: object
      properties:
        ownerPubkey:
          type: string
          minLength: 32
          description: Position owner public key
    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
    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
    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
    ClaimPositionResponse:
      type: object
      properties:
        transaction:
          type: string
          description: Base64 encoded transaction
        txMeta:
          type: object
          properties:
            blockhash:
              type: string
            lastValidBlockHeight:
              type: integer
              minimum: 0
          required:
          - blockhash
          - lastValidBlockHeight
        position:
          type: object
          properties:
            positionPubkey:
              type: string
              description: Position account public key
            marketPubkey:
              type: string
              description: Market account public key
            userPubkey:
              type: string
              description: User public key requesting claim
            ownerPubkey:
              type: string
              description: Position owner public key
            isYes:
              type: boolean
            contracts:
              type: string
              description: Legacy whole-contract quantity settled. Use contractsMicro or contractsDecimal for the exact fractional quantity.
            contractsMicro:
              type: string
              description: Contracts settled in micro-contract units (u64 as string, 1000000 = 1 contract)
            contractsDecimal:
              type: string
              description: Contracts settled as a decimal string
            payoutAmountUsd:
              type: string
              description: Payout amount in micro USD (u64 as string)
          required:
          - positionPubkey
          - marketPubkey
          - userPubkey
          - ownerPubkey
          - isYes
          - contracts
          - payoutAmountUsd
      required:
      - transaction
      - txMeta
      - position
  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)