Foresight API Documentation

import { createPublicClient, createWalletClient, http, type Hex } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const TRADE_API_URL = '<https://api.foresight.now/trade>'

// 1. Get available markets
const marketsResponse = await fetch(`${TRADE_API_URL}/markets`)
const markets = await marketsResponse.json()
console.log('Available markets:', markets)

// 2. Get a quote for a trade
const marketAddress = '0x...' // Market contract address
const amount = '100000000' // 100 USDC in base units (6 decimals)
const outcome = 1 // 1 = YES, 0 = NO
const tradeType = 'Buy'

const quoteResponse = await fetch(`${TRADE_API_URL}/quote`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    market: marketAddress,
    amount: amount,
    outcome: outcome,
    type: tradeType
  })
})
const quote = await quoteResponse.json()
console.log('Trade quote:', quote)

// 3. Check and handle token approval (required for buying)
const account = '0x...' // User wallet address
const tokenAddress = '0x...' // USDC token address
const spenderAddress = '0x...' // Market maker contract address

// Check current allowance
const allowance = await publicClient.readContract({
  address: tokenAddress,
  abi: erc20ABI,
  functionName: 'allowance',
  args: [account, spenderAddress]
})

// If allowance is insufficient, approve the spender
if (allowance < BigInt(amount)) {
  const approveHash = await walletClient.writeContract({
    address: tokenAddress,
    abi: erc20ABI,
    functionName: 'approve',
    args: [spenderAddress, BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')]
  })

  // Wait for approval confirmation
  await publicClient.waitForTransactionReceipt({ hash: approveHash })
  console.log('Token approval confirmed')
}

// 4. Create a trade intent and get execution data
//    POST /trade requires a platform API key.
const executeResponse = await fetch(`${TRADE_API_URL}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string,
  },
  body: JSON.stringify({
    market: marketAddress,
    amount: amount,
    outcome: outcome,
    type: tradeType,
    account: account
  })
})
const tradeData = await executeResponse.json()
console.log('Trade execution data:', tradeData)
// tradeData: { intentId, marketType: 'AMM' | 'CLOB', market, outcome, amount,
//              estimatedReturn, price, tx? (AMM) | typedData? (CLOB) }

// For AMM markets, tradeData.tx is the encoded transaction to send.
// (For CLOB markets you receive tradeData.typedData to sign instead.)
if (tradeData.tx) {
  // Simulate the transaction first (sign/send from the user's own account)
  const callResult = await publicClient.call({
    account: account,
    data: tradeData.tx.data,
    to: tradeData.tx.to,
    value: BigInt(tradeData.tx.value),
  })
  console.log('Simulation result:', callResult)

  // Send the actual transaction
  const PRIVATE_KEY = process.env.PRIVATE_KEY as Hex
  const walletClient = createWalletClient({
    chain: mainnet,
    transport: http(),
  })
  const hash = await walletClient.sendTransaction({
    account: privateKeyToAccount(PRIVATE_KEY),
    data: tradeData.tx.data,
    to: tradeData.tx.to,
    value: BigInt(tradeData.tx.value),
  })
  console.log('Transaction hash:', hash)

  // 5. Save the transaction hash. Call this right after broadcasting —
  //    you do not need to wait for the transaction receipt.
  await fetch(`${TRADE_API_URL}/save`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string,
    },
    body: JSON.stringify({ txHash: hash, chainId: 8453 }), // chainId = chain the trade was sent on
  })
}

// 6. Get user positions and redeem winning positions
async function redeemWinningPositions(userAddress: string) {
  // Get resolved positions
  const positionsResponse = await fetch(`${TRADE_API_URL}/positions?walletAddress=${userAddress}&type=resolved&pg=1&ps=20`)
  const positionsData = await positionsResponse.json()

  // Filter for claimable positions (resolved markets where user has winning shares)
  const claimablePositions = positionsData.positions.filter(position =>
    position.resolutionOutcome === position.outcome && position.totalShareAmount > 0
  )

  console.log(`Found ${claimablePositions.length} claimable positions`)

  // Redeem each claimable position
  for (const position of claimablePositions) {
    try {
      // POST /trade/redeem requires a platform API key.
      const redeemResponse = await fetch(`${TRADE_API_URL}/redeem`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string,
        },
        body: JSON.stringify({
          market: position.market,
          account: userAddress
        })
      })
      const redeemData = await redeemResponse.json()

      if (redeemData.tx) {
        // Simulate the transaction first
        const callResult = await publicClient.call({
          account: redeemData.tx.account,
          data: redeemData.tx.data,
          to: redeemData.tx.to,
          value: BigInt(redeemData.tx.value),
        })
        console.log('Redeem simulation successful')

        // Send the actual transaction
        const redeemHash = await walletClient.sendTransaction({
          data: redeemData.tx.data,
          to: redeemData.tx.to,
          value: BigInt(redeemData.tx.value),
        })
        console.log('Redeem transaction hash:', redeemHash)

        // Wait for confirmation — the indexer auto-processes the redeem.
        // Redeems need no /trade/save or /trade/complete call.
        await publicClient.waitForTransactionReceipt({ hash: redeemHash })
      }
    } catch (error) {
      console.error(`Error redeeming position for market ${position.market}:`, error)
    }
  }
}

// Usage example
// await redeemWinningPositions('0x...') // User wallet address

interface MarketsQuery {
  chainId?: number; // Optional. If omitted, defaults to the legacy default chain.
}

interface MarketInfo {
  address: string;
  question: string;
  marketType: 'AMM' | 'CLOB'; // Which trading API this market needs (a chain can host both)
  outcome1Price: number; // Current price for the YES outcome (index 1)
  outcome0Price: number; // Current price for the NO outcome (index 0)
  endDate: string; // ISO-8601 (market group end)
  volume: number; // All-time cumulative volume in human USD (already normalized by chain decimals — do NOT divide again)
  transactionCount: number; // All-time cumulative trade count
  createdAt: string; // ISO-8601 — when the market instance became tradeable on its chain
}

const markets = await fetch(`${TRADE_API_URL}/markets`) // or `${TRADE_API_URL}/markets?chainId=8453`
const data = await markets.json()

interface TradeQuoteRequest {
  market: string;        // Market contract address
  amount: string;        // Amount in base units (6 decimals for USDC)
  outcome: 0 | 1;       // 0 = NO, 1 = YES
  type: 'Buy' | 'Sell'; // Trade type
  chainId?: number;     // Optional. Auto-resolved from the market when omitted.
}

interface TradeQuote {
  market: string;
  tokenAddress: string;  // Token to approve (collateral for buy; ERC1155 setApprovalForAll for sell)
  amount: string;
  outcome: 0 | 1;
  type: 'Buy' | 'Sell';
  estimatedReturn: string;
  estimatedPricePerShare: number;
}

const quote = await fetch(`${TRADE_API_URL}/quote`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    market: "0x...",
    amount: "100000000", // 100 USDC
    outcome: 1, // YES
    type: "Buy"
  })
})
const data = await quote.json()

interface TradeExecuteRequest {
  market: string;        // Market contract address
  amount: string;        // Amount in base units (6 decimals for USDC)
  outcome: 0 | 1;       // 0 = NO, 1 = YES
  type: 'Buy' | 'Sell'; // Trade type
  account: string;       // User wallet address
  chainId?: number;     // Optional. Auto-resolved from the market when omitted.
}

interface TradeIntentResponse {
  intentId: string;              // ID of the created TransactionIntent
  marketType: 'AMM' | 'CLOB';    // Determines whether `tx` or `typedData` is present
  market: string;
  outcome: 0 | 1;
  amount: string;                // Echoed from the request (base units)
  estimatedReturn: string;       // Shares for buy, USDC for sell (base units)
  price: number;                 // Estimated price per share
  tx?: {                         // AMM only
    to: string;      // Contract address to send transaction to (the market)
    data: string;    // Transaction data (encoded function call)
    value: string;   // ETH value to send (usually "0")
    chainId: number; // Chain the transaction must be submitted on
  };
  typedData?: object;            // CLOB only — EIP-712 typed data to sign
}

const tradeData = await fetch(`${TRADE_API_URL}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string,
  },
  body: JSON.stringify({
    market: "0x...",
    amount: "100000000",
    outcome: 1,
    type: "Buy",
    account: "0x..." // user wallet address
  })
})
const data = await tradeData.json()

// AMM markets: send transaction using the user's wallet client
const hash = await walletClient.sendTransaction({
  data: data.tx.data,
  to: data.tx.to,
  value: BigInt(data.tx.value),
  account: "0x...", // the same user wallet address
})

// POST `/trade/save` - Record the broadcast trade for origin attribution.
// Send the transaction hash right after broadcasting; no need to wait for the receipt.
await fetch(`${TRADE_API_URL}/save`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string,
  },
  body: JSON.stringify({ txHash: hash, chainId: 8453 }),
})

// No /trade/complete call is required — the indexer auto-processes the confirmed transaction.

interface RedeemExecuteRequest {
  market: string;  // Market contract address
  account: string; // User wallet address
  chainId?: number; // Optional. Auto-resolved from the market when omitted.
}

interface RedeemExecuteResponse {
  tx: {
    to: string;      // Contract address to send transaction to
    data: string;    // Transaction data (encoded function call)
    account: string; // User account address
    value: string;   // ETH value to send (usually "0")
  };
  expectedReturn: string; // Expected return amount in base units
  market: string;         // Market address
}

const redeemData = await fetch(`${TRADE_API_URL}/redeem`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string,
  },
  body: JSON.stringify({
    market: "0x...", // Market contract address
    account: "0x..." // User wallet address
  })
})
const data = await redeemData.json()

// Send transaction using wallet client
const hash = await walletClient.sendTransaction({
  data: data.tx.data,
  to: data.tx.to,
  value: BigInt(data.tx.value),
  account: data.tx.account,
})

// Redeems are recorded automatically — no save or completion call needed.

interface PositionsQuery {
  walletAddress: string;           // User wallet address (required)
  type: 'active' | 'resolved';    // Filter by market status (required)
  pg?: number;                    // Page number (default: 1)
  ps?: number;                    // Page size (default: 20, max: 100)
}

interface UserPositionsResponse {
  positions: Array<{
    market: string;              // Market address
    tokenAddress: string;        // Token address for the market shares
    amountInvested: number;      // Amount invested in collateral token (in base units)
    outcome: 0 | 1;             // Outcome index bought (0 for NO, 1 for YES)
    totalShareAmount: number;    // Total share amount held (in base units)
    question: string;          // Market question
    resolutionOutcome: number | null; // Resolution outcome (0 for NO, 1 for YES, -1 for DRAW/TIE; null if market not resolved)
    marketEndDate: string | null;    // Market end date
  }>;
  page: number;                  // Current page number
  pageSize: number;              // Number of items per page
  hasPrevious: boolean;          // Whether there is a previous page
  hasNext: boolean;              // Whether there is a next page
  totalCount: number;            // Total number of positions for a given user
}

const positions = await fetch(`${TRADE_API_URL}/positions?walletAddress=0x...&type=resolved&pg=1&ps=20`)
const data = await positions.json()

// Filter for claimable positions (resolved markets where user has winning shares)
const claimablePositions = data.positions.filter(position =>
  position.resolutionOutcome === position.outcome && position.totalShareAmount > 0
)

// Redeem each claimable position
for (const position of claimablePositions) {
  const redeemData = await fetch(`${TRADE_API_URL}/redeem`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Platform-API-Key': process.env.FORESIGHT_API_KEY as string,
    },
    body: JSON.stringify({
      market: position.market,
      account: "0x..." // User wallet address
    })
  })
  // ... execute redeem transaction
}

interface TradeSaveRequest {
  txHash: string;  // 0x-prefixed 32-byte transaction hash from broadcast
  chainId: number; // EVM chain id the transaction was sent on
}

interface TradeSaveResponse {
  ok: true;
}

// Check current allowance
const allowance = await publicClient.readContract({
  address: tokenAddress, // USDC token address
  abi: erc20ABI,
  functionName: 'allowance',
  args: [userAddress, marketMakerAddress]
})

// Approve if needed (using max uint256 for unlimited approval)
if (allowance < BigInt(tradeAmount)) {
  const approveHash = await walletClient.writeContract({
    address: tokenAddress,
    abi: erc20ABI,
    functionName: 'approve',
    args: [marketMakerAddress, BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')]
  })

  await publicClient.waitForTransactionReceipt({ hash: approveHash })
}