The APIs are separated into just three basic routes:
GET /trade/markets - Get all active markets and details
POST /trade/quote - To get price and number of shares to purchase based on amount to bet
POST /trade - Make a trade
We do have additional APIs to create and fund your own markets for you to create unique opportunities for your own platform and drive your own volume. However, these APIs are only unlocked upon request with our business team. Do contact the team for details.
POST /admin/create - Create a market
POST /admin/fund - Fund a market payout pool
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