Foresight API Swagger

openapi: 3.0.3
info:
  title: Trade API
  description: API to enable trading on Foresight
  version: 1.0.0
  contact:
    name: Foresight Team
servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://api.foresight.now
    description: Production server

paths:
  /trade/markets:
    get:
      tags:
        - Trade
      summary: Gets all active markets and details that are available/active for trading
      description: Retrieve all markets available for trading, with details such as marketAddress, outcomePrices (outcome1 for YES, outcome0 for NO), marketEndDate and the marketQuestion.
      operationId: getTradeableMarkets
      responses:
        '200':
          description: Returns list of active markets with details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketInfoResponseDTO'

  /trade/quote:
    post:
      tags:
        - Trade
      summary: Generates a quote based on the given marketAddress, outcome to bet on (1 for YES, 0 for NO) and amount(USDC). Returns the estimated shares bought for the given amount
      description: Generates a quote based on the given marketAddress, outcome and amount(USDC), with details such as the estimateReturn amount based on the input amount, and the estimatedPricePerShare.
      operationId: getTradeQuote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TradeDTO'
      responses:
        '200':
          description: Quote generated based on the given marketAddress, outcome and amount(USDC).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeQuoteResponseDTO'

  /trade:
    post:
      tags:
        - Trade
      summary: Generates trade calldata neccessary for executing a trade transaction based on the given arguments.
      description: Generates the calldata neccessary to execute the trade, includes the data is returned from /quote (check /quote endpoint)
      operationId: prepareExecuteTrade
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TradeExecuteDTO'
      responses:
        '201':
          description: Quote based on the given marketAddress, outcome and amount, and the neccessary transaction calldata to execute the trade
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeExecuteResponseDTO'

  /trade/redeem:
    post:
      tags:
        - Trade
      summary: Generates redeem calldata necessary for executing a redeem transaction based on given arguments
      description: Generates the calldata necessary to execute a redeem transaction for a given resolved market, and the expected return amount in base units
      operationId: prepareExecuteRedeem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemExecuteDTO'
      responses:
        '200':
          description: Returns the expected return amount in base units and the calldata necessary to execute a redeem transaction for a given resolved market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemExecuteResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '404':
          description: Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'

  /trade/complete:
    post:
      tags:
        - Trade
      summary: (Deprecated) Process transaction with transaction hash
      description: |
        Deprecated: This endpoint is no longer required. An indexer now automatically processes confirmed on-chain transactions and persists them so positions appear without calling this endpoint.
      deprecated: true
      operationId: completeTradeExecution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TradeCompleteRequestDTO'
      responses:
        '200':
          description: Transaction processing result (legacy)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeCompleteResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'

  /trade/positions:
    get:
      tags:
        - Trade
      summary: Get positions for a given user, with pagination support
      description: Retrieve user positions (active or resolved) with pagination support.
      operationId: getUserPositions
      parameters:
        - name: walletAddress
          in: query
          required: true
          description: User wallet address
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
            example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
        - name: type
          in: query
          required: true
          description: Filter positions by market status
          schema:
            type: string
            enum: [active, resolved]
            example: 'active'
        - name: pg
          in: query
          required: false
          description: Page number (default 1)
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: ps
          in: query
          required: false
          description: Page size (default 20)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
      responses:
        '200':
          description: Returns the positions and details for a given user, with pagination support
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPositionsResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'

components:
  schemas:
    TradeType:
      type: string
      enum:
        - Buy
        - Sell
      description: Type of trade operation

    TradeDTO:
      type: object
      required:
        - market
        - amount
        - outcome
        - type
      properties:
        market:
          type: string
          description: Market address
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
          pattern: '^0x[a-fA-F0-9]{40}$'
        amount:
          type: string
          description: Amount in USDC in base units
          example: '100000000'
          pattern: '^[0-9]+$'
        outcome:
          type: integer
          description: Outcome selection
          example: 1
          enum: [0, 1]
        type:
          $ref: '#/components/schemas/TradeType'

    TradeExecuteDTO:
      allOf:
        - $ref: '#/components/schemas/TradeDTO'
        - type: object
          required:
            - account
          properties:
            account:
              type: string
              description: User Address
              example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
              pattern: '^0x[a-fA-F0-9]{40}$'

    TradeQuoteResponseDTO:
      type: object
      required:
        - market
        - tokenAddress
        - amount
        - outcome
        - type
        - estimatedReturn
        - estimatedPricePerShare
      properties:
        market:
          type: string
          description: Market address
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
        tokenAddress:
          type: string
          description: Address of token to call approval on (setApprovalForAll for sell since our market shares are ERC1155)
          example: '0x9F42B4e7A1C16DAF7c09A0ad8F47CF8206C5b9A3'
        amount:
          type: string
          format: bigint
          description: Amount in USDC in base units
          example: '100'
        outcome:
          type: integer
          description: Outcome selection
          example: 1
          enum: [0, 1]
        type:
          $ref: '#/components/schemas/TradeType'
        estimatedReturn:
          type: string
          format: bigint
          description: Estimated return (shares for buy, USDC for sell)
          example: '95.5'
        estimatedPricePerShare:
          type: number
          format: float
          description: Estimated price per share
          example: '0.24'

    TransactionDetailsDTO:
      type: object
      required:
        - to
        - data
        - account
        - value
      properties:
        to:
          type: string
          description: Contract address to send transaction to
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
        data:
          type: string
          description: Encoded function call data
          example: '0x1234567890abcdef...'
        account:
          type: string
          description: Account address executing the trade
          example: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
        value:
          type: string
          description: Value in wei sent with this transaction (typically 0 for USDC trades)
          example: '0'

    TradeExecuteResponseDTO:
      allOf:
        - $ref: '#/components/schemas/TradeQuoteResponseDTO'
        - type: object
          required:
            - tx
          properties:
            tx:
              $ref: '#/components/schemas/TransactionDetailsDTO'

    TradeCompleteRequestDTO:
      type: object
      required:
        - txHash
      properties:
        txHash:
          type: string
          description: Transaction hash to process
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
          pattern: '^0x[a-fA-F0-9]{64}$'

    TradeCompleteResponseDTO:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: Whether the operation was successful
          example: true
        message:
          type: string
          description: Response message
          example: 'Transaction processed successfully'
        data:
          type: object
          nullable: true
          description: Transaction data if successfully processed
          properties:
            txHash: { type: string, description: 'Transaction hash' }
            type: { type: string, enum: ['BUY', 'SELL'] }
            tokenAmount: { type: string, description: 'Token amount bought/sold' }
            usdtAmount: { type: string, description: 'USDT amount spent on the trade' }
            price: { type: string, description: 'Effective price per share of the trade' }
            positionId: { type: string, description: 'Position ID of the shares bought' }
            userAddress: { type: string, description: 'Address of the user who bought the shares' }
            createdAt: { type: string, format: 'date-time', description: 'Date and time of the transaction' }

    MarketInfoResponseDTO:
      type: object
      required:
        - address
        - question
        - yesPrice
        - noPrice
        - endDate
      properties:
        address:
          type: string
          description: Market address
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
        question:
          type: string
          description: Market question
          example: 'Will Bitcoin reach $100,000 by end of 2024?'
        outcome1Price:
          type: number
          format: float
          description: Current price for YES outcome
          example: 0.65
        outcome0Price:
          type: number
          format: float
          description: Current price for NO outcome
          example: 0.35
        endDate:
          type: string
          format: date-time
          description: Market end date
          example: '2024-12-31T23:59:59Z'

    RedeemExecuteDTO:
      type: object
      required:
        - market
        - account
      properties:
        market:
          type: string
          description: Market address
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
          pattern: '^0x[a-fA-F0-9]{40}$'
        account:
          type: string
          description: User Address
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
          pattern: '^0x[a-fA-F0-9]{40}$'

    RedeemExecuteResponseDTO:
      type: object
      required:
        - tx
        - expectedReturn
        - market
      properties:
        tx:
          $ref: '#/components/schemas/TransactionDetailsDTO'
        expectedReturn:
          type: string
          format: bigint
          description: Expected return amount in base units
          example: '100'
        market:
          type: string
          description: Market address
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'

    UserPositionDTO:
      type: object
      required:
        - market
        - tokenAddress
        - amountInvested
        - outcome
        - totalShareAmount
        - question
        - resolutionOutcome
        - marketEndDate
      properties:
        market:
          type: string
          description: Market address
          example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
        tokenAddress:
          type: string
          description: Token address for the market shares
          example: '0x9F42B4e7A1C16DAF7c09A0ad8F47CF8206C5b9A3'
        amountInvested:
          type: number
          description: Amount invested in collateral token (in base units)
          example: 100.5
        outcome:
          type: integer
          description: Outcome index bought (0 for NO, 1 for YES)
          enum: [0, 1]
          example: 1
        totalShareAmount:
          type: number
          description: Total share amount held (in base units)
          example: 95.5
        question:
          type: string
          description: Market question
          example: 'Will Bitcoin reach $100,000 by end of 2024?'
        resolutionOutcome:
          type: integer
          nullable: true
          description: Resolution outcome (null if market not resolved)
          example: 1
        marketEndDate:
          type: string
          format: date-time
          nullable: true
          description: Market end date
          example: '2024-12-31T23:59:59Z'

    UserPositionsResponseDTO:
      type: object
      required:
        - positions
        - page
        - pageSize
        - hasPrevious
        - hasNext
        - totalCount
      properties:
        positions:
          type: array
          items:
            $ref: '#/components/schemas/UserPositionDTO'
        page:
          type: integer
          description: Current page number
          example: 1
        pageSize:
          type: integer
          description: Number of items per page
          example: 20
        hasPrevious:
          type: boolean
          description: Whether there is a previous page
          example: false
        hasNext:
          type: boolean
          description: Whether there is a next page
          example: true
        totalCount:
          type: integer
          description: Total number of positions for a given user
          example: 45

    BadRequestError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Error message
          example: 'Bad request'
        statusCode:
          type: integer
          description: HTTP status code
          example: 400
        error:
          type: string
          description: Error type
          example: 'Bad Request'

    NotFoundError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Error message
          example: 'Market not found'
        statusCode:
          type: integer
          description: HTTP status code
          example: 404
        error:
          type: string
          description: Error type
          example: 'Not Found'

    InternalServerError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Error message
          example: 'Failed to get trade quote'
        statusCode:
          type: integer
          description: HTTP status code
          example: 500
        error:
          type: string
          description: Error type
          example: 'Internal Server Error'

tags:
  - name: Trade
    description: Trading endpoints for Foresight. Includes endpoints for getting active markets, generating quotes for trades and getting calldata to execute a trade