Below is the Swagger API yaml for reference:
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/complete:
post:
tags:
- Trade
summary: (Deprecated) Process transaction with transaction hash, and create an entry in the database.
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.
operationId: completeTradeExecution
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TradeCompleteRequestDTO'
responses:
'200':
description: Transaction processing result
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'
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'
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'
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