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, the marketQuestion, and trading-activity metadata (volume in human USD, transactionCount, createdAt).
operationId: getTradeableMarkets
parameters:
- name: chainId
in: query
required: false
description: Optional chain network id. If omitted, tradeable markets default to the legacy default chain.
schema:
type: integer
minimum: 1
example: 8453
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: Create a trade intent and return execution data. Requires a platform API key.
description: >
Reads the market's model (AMM vs CLOB), creates a TransactionIntent, and returns
the data needed to execute. For AMM markets the response includes an encoded `tx`
block to sign and send; for CLOB markets it includes an EIP-712 `typedData` block
to sign. Requires the `X-Platform-API-Key` header (or `Authorization: Bearer <apiKey>`).
operationId: prepareExecuteTrade
security:
- PlatformApiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TradeExecuteDTO'
responses:
'201':
description: Intent created. AMM responses include a `tx` block; CLOB responses include a `typedData` block.
content:
application/json:
schema:
$ref: '#/components/schemas/TradeIntentResponseDTO'
'401':
description: Missing or invalid platform API key
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'404':
description: Market not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/trade/redeem:
post:
tags:
- Trade
summary: Generates redeem calldata necessary for executing a redeem transaction based on given arguments. Requires a platform API key.
description: "Generates the calldata necessary to execute a redeem transaction for a given resolved market, and the expected return amount in base units. Requires the `X-Platform-API-Key` header (or `Authorization: Bearer <apiKey>`)."
operationId: prepareExecuteRedeem
security:
- PlatformApiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RedeemExecuteDTO'
responses:
'201':
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'
'401':
description: Missing or invalid platform API key
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'404':
description: Market not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/trade/save:
post:
tags:
- Trade
summary: Save a broadcast trade's transaction hash
description: |
Send the transaction hash here right after broadcasting a trade. You do not need to wait for the transaction receipt.
operationId: saveTrade
parameters:
- name: X-Platform-API-Key
in: header
required: true
description: Your platform API key
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TradeSaveRequestDTO'
responses:
'201':
description: Trade saved
content:
application/json:
schema:
$ref: '#/components/schemas/TradeSaveResponseDTO'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
/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'
chainId:
type: integer
description: Optional chain network id. If omitted, the API resolves the market chain automatically and falls back to the default chain for legacy markets.
minimum: 1
example: 8453
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'
TradeSaveRequestDTO:
type: object
required:
- txHash
- chainId
properties:
txHash:
type: string
description: Transaction hash from broadcast
example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
pattern: '^0x[a-fA-F0-9]{64}$'
chainId:
type: integer
description: EVM chain id the transaction was sent on
example: 8453
TradeSaveResponseDTO:
type: object
required:
- ok
properties:
ok:
type: boolean
description: Always true
example: true
MarketInfoResponseDTO:
type: object
required:
- address
- question
- marketType
- outcome1Price
- outcome0Price
- endDate
- volume
- transactionCount
- createdAt
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?'
marketType:
type: string
enum: ['AMM', 'CLOB']
description: >-
Trading model for this market. AMM → execute via POST /trade
(returns tx). CLOB → sign the EIP-712 order. A chain can host both,
so callers must branch on this.
example: 'AMM'
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 group end date
example: '2024-12-31T23:59:59Z'
volume:
type: number
description: >-
All-time cumulative trading volume in human USD, already normalized
by the chain's collateral decimals (raw / 10^chainDecimals) — do NOT
divide again client-side.
example: 12345.67
transactionCount:
type: integer
description: All-time cumulative number of trades on this market.
example: 421
createdAt:
type: string
format: date-time
description: When this market instance became tradeable on its chain (ISO 8601).
example: '2024-01-15T08:30:00Z'
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}$'
chainId:
type: integer
description: Optional chain network id. If omitted, the API resolves the market chain automatically and falls back to the default chain for legacy markets.
minimum: 1
example: 8453
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 (0 for NO, 1 for YES, -1 for DRAW/TIE; null if market not resolved)
enum: [-1, 0, 1]
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'
IntentTxDTO:
type: object
required:
- to
- data
- value
- chainId
properties:
to:
type: string
description: Contract address to send the transaction to (the market address for AMM trades)
example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
data:
type: string
description: Encoded function call data
example: '0x1234567890abcdef...'
value:
type: string
description: Value in wei sent with this transaction (typically '0' for USDC trades)
example: '0'
chainId:
type: integer
description: Chain id the transaction must be submitted on
example: 8453
TradeIntentResponseDTO:
type: object
required:
- intentId
- marketType
- market
- outcome
- amount
- estimatedReturn
- price
properties:
intentId:
type: string
description: ID of the TransactionIntent created for this trade
example: 'clx1a2b3c4d5e6f7g8h9'
marketType:
type: string
enum: [AMM, CLOB]
description: Market model. AMM responses carry a `tx` block; CLOB responses carry a `typedData` block.
example: 'AMM'
market:
type: string
description: Market address (echoed from the request)
example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
outcome:
type: integer
enum: [0, 1]
description: Outcome selection (echoed from the request)
example: 1
amount:
type: string
description: Amount in USDC base units (echoed from the request)
example: '100000000'
estimatedReturn:
type: string
format: bigint
description: Estimated return (shares for buy, USDC for sell) in base units
example: '95500000'
price:
type: number
format: float
description: Estimated price per share
example: 0.24
tx:
description: AMM only — encoded transaction to sign and send. Absent for CLOB markets.
allOf:
- $ref: '#/components/schemas/IntentTxDTO'
typedData:
type: object
additionalProperties: true
description: CLOB only — EIP-712 typed data to sign. Absent for AMM markets.
securitySchemes:
PlatformApiKey:
type: apiKey
in: header
name: X-Platform-API-Key
description: "Platform API key. May also be supplied as `Authorization: Bearer <apiKey>`."
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
