my-forecast-agent
cd my-forecast-agent
bun install # or: pnpm install / npm install
```
3. Create your `.env` file:
```bash
# Required
OPENROUTER_API_KEY=your-openrouter-key
EVM_PRIVATE_KEY=your-private-key
# Optional: Enable autonomous mode
AUTONOMOUS_MODE=forecast,trade
```
4. Run locally:
```bash
bun run dev
```
5. Push changes to your repo. Enable Autodeploy in Railway so pushes trigger automatic redeployments.
#### Manual Deployment
For other platforms or manual deployment, see the [Railway CLI guide](https://docs.railway.com/guides/cli) or build the project directly:
```bash
bun run build
bun run start
```
The agent can run on any platform that supports Node.js and Bun.
import TypeScriptContent from './_forecasting-agent-typescript.mdx'
:::info
**We strongly recommend** using Cursor, Codex, Claude Code, or any other LLM-powered code editor. You may be surprised by how far you can get without writing code yourself. [See Get Started](/builder-guide/getting-started/get-started)
:::
## Deploy a Forecasting Agent
Build an autonomous forecasting agent that generates predictions and publishes forecasts to the [Ethereum Attestation Service](https://docs.attest.sh/) on [Arbitrum](https://arbitrum.io).
Forecasts are displayed in the [Sapience app](https://sapience.xyz/forecasts). Forecasters with the most early and accurate predictions are ranked on the [leaderboard](https://sapience.xyz/leaderboard#accuracy).
For a full-featured agent framework with trading capabilities, see the [ElizaOS Agent](/builder-guide/guides/elizaos-agent) guide.
:::info
**We strongly recommend** using Cursor, Codex, Claude Code, or any other LLM-powered code editor. You may be surprised by how far you can get without writing code yourself. [See Get Started](/builder-guide/getting-started/get-started)
:::
## Liquidity Provisioning Bots
This guide builds on the previous bot guides. Complete the [Forecasting Agent](/builder-guide/guides/forecasting-agent) and [Trading Bots](/builder-guide/guides/trading-bots) first to understand basic bot setup and market interaction patterns.
### What is Liquidity Provisioning?
**Liquidity provisioning** means depositing your capital into a market to facilitate trading for others. When traders want to buy or sell, they trade against your liquidity. In return, you earn fees on every trade that passes through your position.
Think of it like being a **market maker**:
* Traditional traders: "I want to buy 100 Yes shares at 50 USDe"
* Liquidity providers: "I'll provide liquidity between 0.45-0.55 USDe per share, so anyone can trade in that range"
#### How it works on Sapience
1. **Deposit collateral** (e.g., 1,000 USDe) and choose a **price range** (e.g., 0.40-0.60 USDe per Yes Share)
2. **The protocol automatically** converts your collateral into YES and NO tokens across that range
3. **Traders pay fees** when they swap through your range (you earn these fees)
4. **Your inventory shifts** as price moves—if price rises, you accumulate more NO tokens; if price falls, you get more YES tokens
5. **At settlement**, your tokens convert to their final values (0 or 1 USDe), and you keep all fees earned
#### Key benefits
* **Passive income**: Earn fees without actively trading
* **Automated execution**: No need to manually place and cancel orders
* **Flexible ranges**: Choose tight ranges for higher fees or wide ranges for more trading volume
* **Multiple positions**: Run several strategies simultaneously
#### Key risks
* **Inventory risk**: You might end up holding the losing side at settlement
* **Impermanent loss**: Your final payout might be less than just holding the winning tokens
* **Fee dependency**: You need to earn enough fees to compensate for potential losses
***
### For CLOB Market Makers
If you're familiar with traditional order book market making, here's how LP translates:
**CLOB**: Place discrete bid/ask orders → **LP**: Provide liquidity across continuous price ranges\
**CLOB**: Cancel/replace orders as price moves → **LP**: Adjust range boundaries or add/remove liquidity\
**CLOB**: Inventory changes when orders fill → **LP**: Inventory shifts continuously as price moves through your range\
**CLOB**: Earn spread on filled orders → **LP**: Earn fees on all volume passing through your range
**Advantages of LP over CLOB:**
* No latency wars or order replacement races
* Continuous fee earning vs. discrete fills
* Built-in inventory management through range selection
* Lower operational overhead
***
### LP Strategy Examples
#### Wide Range Market Making
**Strategy**: Provide liquidity across a broad price range to capture volume from large price movements while minimizing the risk of going out of range.
This strategy works well for volatile markets where you want steady fee income without constantly rebalancing positions.
> **Note**: These examples use internal hooks from the Sapience monorepo (`packages/app/src/hooks/contract`). If building a standalone app, you'll need to implement equivalent hooks using viem's contract interaction methods or adapt the SDK patterns.
```tsx
import { useCreateLiquidityQuoter, useCreateLP } from '@sapience/app/hooks/contract';
import { priceToTick } from '@sapience/app/lib/utils/tickUtils';
async function wideRangeStrategy({ marketAddress, marketAbi, chainId, marketId, tickSpacing = 200 }) {
const collateralAmount = '2000'; // $2000 position size
// Wide range: 20% to 80% (captures most price action)
const lowPrice = 0.20;
const highPrice = 0.80;
const lowTick = priceToTick(lowPrice, tickSpacing);
const highTick = priceToTick(highPrice, tickSpacing);
const { amount0, amount1 } = useCreateLiquidityQuoter({
marketAddress,
marketAbi,
marketId: BigInt(marketId),
chainId,
collateralAmount,
lowTick,
highTick,
enabled: true,
});
const { createLP } = useCreateLP({
marketAddress,
marketAbi,
chainId,
marketId: BigInt(marketId),
collateralAmount,
lowPriceTick: lowTick,
highPriceTick: highTick,
amount0,
amount1,
slippagePercent: 1.0, // 1% slippage tolerance
});
await createLP();
console.log(`Wide range LP created: ${lowPrice}-${highPrice}`);
}
```
#### Tight Range Scalping
**Strategy**: Place liquidity in a narrow band around the current price to maximize fee APY. Requires active management to stay in range.
Best for stable markets or when you have strong conviction about price staying within a tight range.
```tsx
async function tightRangeStrategy({
marketAddress,
marketAbi,
chainId,
marketId,
currentPrice,
tickSpacing = 200
}) {
const collateralAmount = '500'; // Smaller position for active management
// Tight 5% range around current price
const spread = 0.025; // 2.5% on each side
const lowPrice = Math.max(0.01, currentPrice - spread);
const highPrice = Math.min(0.99, currentPrice + spread);
const lowTick = priceToTick(lowPrice, tickSpacing);
const highTick = priceToTick(highPrice, tickSpacing);
const { amount0, amount1 } = useCreateLiquidityQuoter({
marketAddress,
marketAbi,
marketId: BigInt(marketId),
chainId,
collateralAmount,
lowTick,
highTick,
enabled: true,
});
const { createLP } = useCreateLP({
marketAddress,
marketAbi,
chainId,
marketId: BigInt(marketId),
collateralAmount,
lowPriceTick: lowTick,
highPriceTick: highTick,
amount0,
amount1,
slippagePercent: 0.3, // Tight slippage for precise execution
});
await createLP();
console.log(`Tight range LP created: ${lowPrice.toFixed(3)}-${highPrice.toFixed(3)}`);
}
// Rebalancing function for tight range strategy
async function rebalanceTightRange({
positionId,
currentPrice,
currentLow,
currentHigh,
marketAddress,
marketAbi,
chainId
}) {
// Check if current price is near range edges
const priceRange = currentHigh - currentLow;
const distanceFromLow = currentPrice - currentLow;
const distanceFromHigh = currentHigh - currentPrice;
// Rebalance if price is within 20% of range edges
if (distanceFromLow < priceRange * 0.2 || distanceFromHigh < priceRange * 0.2) {
console.log('Rebalancing tight range position...');
// Close current position
await closeLiquidityPosition({ positionId, marketAddress, marketAbi, chainId });
// Create new position centered on current price
await tightRangeStrategy({
marketAddress,
marketAbi,
chainId,
marketId: positionId,
currentPrice
});
}
}
```
#### Inventory-Aware Skewed Liquidity
**Strategy**: Skew your liquidity based on your forecast and current inventory to optimize for both fees and directional exposure.
Perfect when you have a forecast but want to earn fees while expressing that view.
```tsx
async function skewedLiquidityStrategy({
marketAddress,
marketAbi,
chainId,
marketId,
forecast, // Your probability forecast (0-1)
currentInventory, // { yesTokens, noTokens }
tickSpacing = 200
}) {
const collateralAmount = '1500';
// Skew range based on forecast and inventory
const baseWidth = 0.15; // 15% base width
// If forecast is bullish (>0.5), skew range higher
// If forecast is bearish (<0.5), skew range lower
const skewFactor = (forecast - 0.5) * 0.2; // Max 10% skew
// Adjust for inventory imbalance
const inventoryTotal = currentInventory.yesTokens + currentInventory.noTokens;
const inventorySkew = inventoryTotal > 0
? (currentInventory.noTokens - currentInventory.yesTokens) / inventoryTotal * 0.1
: 0;
const centerPrice = forecast + skewFactor + inventorySkew;
const lowPrice = Math.max(0.01, centerPrice - baseWidth / 2);
const highPrice = Math.min(0.99, centerPrice + baseWidth / 2);
const lowTick = priceToTick(lowPrice, tickSpacing);
const highTick = priceToTick(highPrice, tickSpacing);
console.log(`Skewed LP: forecast=${forecast.toFixed(3)}, range=${lowPrice.toFixed(3)}-${highPrice.toFixed(3)}`);
const { amount0, amount1 } = useCreateLiquidityQuoter({
marketAddress,
marketAbi,
marketId: BigInt(marketId),
chainId,
collateralAmount,
lowTick,
highTick,
enabled: true,
});
const { createLP } = useCreateLP({
marketAddress,
marketAbi,
chainId,
marketId: BigInt(marketId),
collateralAmount,
lowPriceTick: lowTick,
highPriceTick: highTick,
amount0,
amount1,
slippagePercent: 0.7,
});
await createLP();
}
```
#### Multi-Range Grid Strategy
**Strategy**: Create multiple LP positions at different price levels to capture fees across the entire market range while managing inventory risk.
Excellent for earning consistent fees while limiting exposure to any single price range.
```tsx
async function gridStrategy({
marketAddress,
marketAbi,
chainId,
marketId,
totalCollateral = '3000',
numRanges = 5,
tickSpacing = 200
}) {
const collateralPerRange = (parseFloat(totalCollateral) / numRanges).toString();
const positions = [];
// Create 5 ranges across the market
for (let i = 0; i < numRanges; i++) {
const rangeWidth = 0.15; // 15% width per range
const rangeCenter = 0.1 + (i * 0.8 / (numRanges - 1)); // Spread from 10% to 90%
const lowPrice = Math.max(0.01, rangeCenter - rangeWidth / 2);
const highPrice = Math.min(0.99, rangeCenter + rangeWidth / 2);
const lowTick = priceToTick(lowPrice, tickSpacing);
const highTick = priceToTick(highPrice, tickSpacing);
const { amount0, amount1 } = useCreateLiquidityQuoter({
marketAddress,
marketAbi,
marketId: BigInt(marketId),
chainId,
collateralAmount: collateralPerRange,
lowTick,
highTick,
enabled: true,
});
const { createLP } = useCreateLP({
marketAddress,
marketAbi,
chainId,
marketId: BigInt(marketId),
collateralAmount: collateralPerRange,
lowPriceTick: lowTick,
highPriceTick: highTick,
amount0,
amount1,
slippagePercent: 0.8,
});
await createLP();
positions.push({ lowPrice, highPrice, collateral: collateralPerRange });
console.log(`Grid range ${i + 1}: ${lowPrice.toFixed(3)}-${highPrice.toFixed(3)}`);
// Add delay between positions to avoid rate limiting
await new Promise(resolve => setTimeout(resolve, 2000));
}
return positions;
}
```
#### Dynamic Range Adjustment
**Strategy**: Automatically adjust your LP ranges based on market volatility and time to resolution.
Adapts to changing market conditions without manual intervention.
```tsx
import { useModifyLP, useModifyLiquidityQuoter } from '@sapience/app/hooks/contract';
import { priceToTick } from '@sapience/app/lib/utils/tickUtils';
async function dynamicRangeStrategy({
marketAddress,
marketAbi,
chainId,
marketId,
positionId,
currentLiquidity,
currentPrice,
volatility, // Recent price volatility (0-1)
timeToResolution, // Hours until market resolves
tickSpacing = 200
}) {
// Adjust range width based on volatility and time
let rangeWidth = 0.10; // Base 10% width
// Widen range during high volatility
if (volatility > 0.05) rangeWidth *= 1.5;
if (volatility > 0.10) rangeWidth *= 2.0;
// Narrow range as resolution approaches (less time for mean reversion)
if (timeToResolution < 24) rangeWidth *= 0.8; // Within 24 hours
if (timeToResolution < 6) rangeWidth *= 0.6; // Within 6 hours
if (timeToResolution < 1) rangeWidth *= 0.4; // Within 1 hour
// Calculate new range
const lowPrice = Math.max(0.01, currentPrice - rangeWidth / 2);
const highPrice = Math.min(0.99, currentPrice + rangeWidth / 2);
const lowTick = priceToTick(lowPrice, tickSpacing);
const highTick = priceToTick(highPrice, tickSpacing);
console.log(`Dynamic range adjustment: ${lowPrice.toFixed(3)}-${highPrice.toFixed(3)} (vol: ${volatility.toFixed(3)}, hours: ${timeToResolution.toFixed(1)})`);
// Remove current liquidity
const { modifyLP: removeLP } = useModifyLP({
marketAddress,
marketAbi,
chainId,
positionId: String(positionId),
mode: 'remove',
liquidityDelta: currentLiquidity,
amount0: BigInt(0),
amount1: BigInt(0),
collateralDelta: '0',
slippagePercent: 1.0,
});
await removeLP();
// Create new position with adjusted range
const collateralAmount = '1000';
const { amount0, amount1 } = useCreateLiquidityQuoter({
marketAddress,
marketAbi,
marketId: BigInt(marketId),
chainId,
collateralAmount,
lowTick,
highTick,
enabled: true,
});
const { createLP } = useCreateLP({
marketAddress,
marketAbi,
chainId,
marketId: BigInt(marketId),
collateralAmount,
lowPriceTick: lowTick,
highPriceTick: highTick,
amount0,
amount1,
slippagePercent: 1.0,
});
await createLP();
}
// Helper function to calculate recent volatility
function calculateVolatility(priceHistory) {
if (priceHistory.length < 2) return 0;
const returns = [];
for (let i = 1; i < priceHistory.length; i++) {
returns.push(Math.log(priceHistory[i] / priceHistory[i - 1]));
}
const mean = returns.reduce((sum, r) => sum + r, 0) / returns.length;
const variance = returns.reduce((sum, r) => sum + Math.pow(r - mean, 2), 0) / returns.length;
return Math.sqrt(variance);
}
```
#### Risk Management Utilities
**Essential functions for managing LP positions safely:**
```tsx
import { useSapienceWriteContract } from '@sapience/app/hooks/blockchain/useSapienceWriteContract';
// Monitor and close positions approaching dangerous inventory levels
async function inventoryRiskManager({
positions, // Array of your LP positions with current inventory
maxInventoryRisk = 0.3 // Max 30% of position value in losing tokens
}) {
for (const position of positions) {
const { positionId, yesTokens, noTokens, currentPrice, marketAddress, marketAbi, chainId } = position;
const totalTokens = yesTokens + noTokens;
if (totalTokens === 0) continue;
// Calculate inventory risk
const yesValue = yesTokens * currentPrice;
const noValue = noTokens * (1 - currentPrice);
const totalValue = yesValue + noValue;
// Risk is the percentage of value in the likely losing side
const yesRisk = currentPrice < 0.5 ? yesValue / totalValue : 0;
const noRisk = currentPrice > 0.5 ? noValue / totalValue : 0;
const inventoryRisk = Math.max(yesRisk, noRisk);
if (inventoryRisk > maxInventoryRisk) {
console.log(`High inventory risk detected: ${inventoryRisk.toFixed(3)} > ${maxInventoryRisk}`);
console.log(`Closing position ${positionId}...`);
await closeLiquidityPosition({
positionId,
marketAddress,
marketAbi,
chainId
});
}
}
}
// Close a liquidity position
async function closeLiquidityPosition({ positionId, marketAddress, marketAbi, chainId }) {
const { writeContract } = useSapienceWriteContract();
const deadline = BigInt(Math.floor(Date.now() / 1000) + 30 * 60); // 30 min deadline
await writeContract({
address: marketAddress,
abi: marketAbi,
functionName: 'closeLiquidityPosition',
args: [{
positionId: BigInt(positionId),
amount0Min: BigInt(0), // Accept any amount (adjust for slippage protection)
amount1Min: BigInt(0),
tradeSlippage: BigInt(1e16), // 1% max slippage
deadline,
}],
chainId,
});
}
// Emergency exit: close all positions
async function emergencyExitAll(positions) {
console.log(`Emergency exit: closing ${positions.length} positions...`);
for (const position of positions) {
try {
await closeLiquidityPosition(position);
console.log(`Closed position ${position.positionId}`);
} catch (error) {
console.error(`Failed to close position ${position.positionId}:`, error);
}
}
}
```
***
### Best Practices
**Position Sizing:**
* Start small while learning (10-20% of your intended size)
* Scale up gradually as you understand fee patterns and inventory dynamics
* Never risk more than you can afford to lose entirely
**Risk Management:**
* Set maximum inventory limits per position and across all positions
* Monitor time to resolution—reduce exposure as settlement approaches
* Use stop-losses based on unrealized P\&L, not just token ratios
**Fee Optimization:**
* Analyze historical volume patterns to place ranges where trading activity is highest
* Consider gas costs—don't create/modify positions too frequently
* Track fee APY vs. inventory risk to optimize range selection
**Operational:**
* Always set reasonable slippage tolerances (0.5-2% depending on market conditions)
* Ensure sufficient gas tokens for position management
* Keep detailed logs of position performance for strategy refinement
***
### Next Steps
Now that you understand liquidity provisioning strategies, you can:
1. **Combine with forecasting**: Use your forecasting agent's predictions to inform LP range placement
2. **Build hybrid strategies**: Mix LP positions with directional trading from your trading bot
3. **Create custom strategies**: Adapt these examples to your specific market views and risk tolerance
4. **Scale systematically**: Start with one strategy, measure performance, then expand
The key to successful LP bot operation is starting simple, measuring everything, and iterating based on real performance data.
import TypeScriptContent from './_market-making-agent-typescript.mdx'
:::info
**We strongly recommend** using Cursor, Codex, Claude Code, or any other LLM-powered code editor. You may be surprised by how far you can get without writing code yourself. [See Get Started](/builder-guide/getting-started/get-started)
:::
## Deploy a Market Making Agent
Build an agent that provides liquidity by [bidding in auctions to make prediction market trades](https://sapience.xyz/terminal) with odds based on forecasts generated upon request.
Your resulting counterparty positions (in which just one pick must resolve in your favor to win) are listed on your profile in the Sapience app and your profit/loss is ranked on the [leaderboard](https://sapience.xyz/leaderboard).
:::info
**We strongly recommend** using Cursor, Codex, Claude Code, or any other LLM-powered code editor. You may be surprised by how far you can get without writing code yourself. [See Get Started](/builder-guide/getting-started/get-started)
:::
## Apps and Interfaces
Build your own prediction market products by customizing the open source [Sapience app](https://sapience.xyz) or starting fresh with [the components in the SDK](/builder-guide/storybook).
:::code-group
### Customize the Sapience App
Fork and ship your own version of the Sapience app. If you run into trouble at any step, ask the Cursor agent in the chat panel to diagnose and fix issues.
#### Clone the repository using Cursor
[Install Cursor](/builder-guide/getting-started/get-started#cursor-setup) and then:
1. Open the Command Palette in Cursor (Cmd/Ctrl+Shift+P) and choose "Git: Clone".
2. Paste the repo URL: `https://github.com/sapiencexyz/sapience.git`
3. Choose a destination folder, then open the cloned repository in Cursor.
4. If prompted, "Trust the authors" and install recommended extensions.
#### Run your copy of the app
Open the terminal in Cursor (Ctrl+\`), then run these from the repository root:
```bash
pnpm install
pnpm dev:app
```
**Prerequisites**:
* Node.js >= 20.14
* pnpm 9.x (install with `npm install -g pnpm@9`)
If you need help installing these, use the Cursor agent or see the [Get Started guide](/builder-guide/getting-started/get-started).
#### Customize the app
Use the Cursor chat panel to prompt the agent to implement your change. Describe the change in plain language and ask it to write/apply the edit, run the app, and fix any errors.
For example:
* Prompt an update such as: "If a user enters a wager amount greater than 1000, render the responsible wager warning text in aLtErNaTiNg CaSe."
* Review the code changes and ask the agent if you have questions about the implementation.
* Verify your change live at `http://localhost:3000`.
#### Push your version to GitHub
1. [Create a GitHub account](/builder-guide/getting-started/get-started#git-setup) if you don't already have one.
2. In GitHub, open `sapiencexyz/sapience` and click "Fork" to create your copy.
3. Point your local repo at your fork:
Open the terminal in Cursor (Ctrl+\`), then run these from the repository root:
```bash
git remote rename origin upstream
git remote add origin https://github.com//sapience.git
git checkout -b my-customization
git add -A && git commit -m "Customize position form warning"
git push -u origin my-customization
```
#### Deploy to Vercel
1. In [Vercel](https://vercel.com), create a New Project and import your fork.
2. Root Directory: `packages/app`.
3. Framework Preset: Next.js (auto).
4. Install Command: `pnpm install --frozen-lockfile`.
5. Build Command: `pnpm build`.
6. Deploy.
#### Contribute a pull request
1. Open a Pull Request from your fork/branch to `sapiencexyz/sapience:main`.
2. Describe what you changed and why. Include screenshots or a brief demo if relevant.
3. Respond to any review feedback; once approved, your improvements can be merged to the main Sapience app.
### Build from Scratch with the SDK
Scaffold a Next.js app that uses the `@sapience/sdk` package for forms and components, and wires data via GraphQL and the Quoter/Auction APIs.
#### Create a new Next.js app
Prerequisites: Node >= 20.14 and pnpm 9.x.
```bash
pnpm create next-app@14.2.30 my-sapience-app --ts --tailwind --eslint --app --use-pnpm --src-dir
cd my-sapience-app
```
This creates a Next.js 14.2.30 app, which is the version supported by `@sapience/sdk`.
#### Install @sapience/sdk
```bash
pnpm add @sapience/sdk
```
#### Install peer dependencies
`@sapience/sdk` expects certain libraries to be provided by your app. Install the core set below, then add optional ones as you use the corresponding components.
**Core peer deps:**
```bash
pnpm add -E next@14.2.30 react@19.1.0 react-dom@19.1.0 react-hook-form@7.53.0 @tanstack/react-query@5.56.2 wagmi@2.14.16 viem@2.23.5 graphql@16.11.0 @apollo/client@3.12.4 lucide-react@0.461.0 lightweight-charts@4.2.1 framer-motion@12.19.1 next-themes@0.3.0
```
**Optional/feature-specific peer deps** (install only if needed):
```bash
pnpm add -E @rainbow-me/rainbowkit@2.1.6 @tanstack/react-table@8.21.2 date-fns@3.6.0 dayjs@1.11.13 jsbi@3.2.5 react-countup@6.5.3 next-pwa@5.6.0 @uniswap/sdk-core@5.4.0 @uniswap/v3-core@1.0.1 @uniswap/v3-sdk@3.14.0
```
Tip: You can always check the exact versions in `@sapience/sdk`'s `peerDependencies` and match them with `-E`.
#### Start the dev server
```bash
pnpm dev
```
#### Import components and hooks
```tsx
import { TradeForm } from '@sapience/ui';
```
#### Connect data
* **GraphQL**: fetch markets, prices, and positions
* **Quoter**: size your trades with price constraints
* **Auction WS**: submit/receive quotes for Auction Markets
* **MCP**: optional agentic tools for research/trading flows
```typescript
// Quoter URL builder example
function toQuoteUrl(params: {
base: string;
chainId: number;
marketGroupAddress: string;
marketId: number;
expectedPrice: number;
collateralAvailable: bigint;
maxIterations?: number;
priceLimit?: number;
}) {
const { base, chainId, marketGroupAddress, marketId, expectedPrice, collateralAvailable, maxIterations, priceLimit } = params;
const qs = new URLSearchParams();
qs.set('expectedPrice', String(expectedPrice));
qs.set('collateralAvailable', String(collateralAvailable));
if (maxIterations) qs.set('maxIterations', String(maxIterations));
if (priceLimit) qs.set('priceLimit', String(priceLimit));
return `${base}/quoter/${chainId}/${marketGroupAddress}/${marketId}/?${qs.toString()}`;
}
```
#### Example page
```tsx
import { useMemo, useState } from 'react';
import { TradeForm } from '@sapience/ui';
export default function TradePage() {
const [baseUrl] = useState('https://api.sapience.xyz');
const chainId = 1;
const marketGroupAddress = '0x...';
const marketId = 1;
const getEstimatedCost = useMemo(() => {
return async (size: string, direction: 'Long' | 'Short') => {
// naive example: call quoter to size collateral given a target price
const expectedPrice = direction === 'Long' ? 0.55 : 0.45;
const collateralAvailable = BigInt(1e18); // 1 token in wei
const url = toQuoteUrl({
base: baseUrl,
chainId,
marketGroupAddress,
marketId,
expectedPrice,
collateralAvailable,
});
const res = await fetch(url);
const data = await res.json();
// return collateral cost estimate string (for demo use expected maxSize)
return data.maxSize ?? '0';
};
}, [baseUrl]);
async function onTradeSubmit(values: { size: string; direction: 'Long' | 'Short'; slippage: string; }) {
// Integrate with write logic or relayer
console.log('submit trade', values);
}
return (
);
}
```
#### GraphQL example
```typescript
import { GraphQLClient, gql } from 'graphql-request';
const client = new GraphQLClient('https://api.sapience.xyz/graphql');
const MarketsQuery = gql`
query Markets {
markets { id title status }
}
`;
export async function fetchMarkets() {
return client.request(MarketsQuery);
}
```
#### Theming and UI
`@sapience/ui` ships with shadcn-like primitives and a Tailwind preset. Import the preset and include it in your Tailwind config.
```typescript
// tailwind.config.ts
import type { Config } from 'tailwindcss'
import sapiencePreset from '@sapience/ui/tailwind-preset'
export default {
presets: [sapiencePreset],
content: [
'./pages/**/*.{ts,tsx}',
'./components/**/*.{ts,tsx}',
'./app/**/*.{ts,tsx}',
'./node_modules/@sapience/ui/**/*.{js,mjs,ts,tsx}'
],
} satisfies Config
```
#### Next Steps
* Add market data via [GraphQL](/builder-guide/api/graphql)
* Use the [Quoter](/builder-guide/api/quoter) to compute max size and price constraints
* Add [Auction Relayer](/builder-guide/api/auction-relayer) for batch markets and limit-like quotes
* Browse available [UI Components](/builder-guide/storybook) in Storybook
:::
import TypeScriptContent from './_trading-agent-typescript.mdx'
:::info
**We strongly recommend** using Cursor, Codex, Claude Code, or any other LLM-powered code editor. You may be surprised by how far you can get without writing code yourself. [See Get Started](/builder-guide/getting-started/get-started)
:::
## Deploy a Trading Agent
Build an automated [prediction market](https://sapience.xyz/markets) trading agent that generates predictions and submits them with a [1 USDe](https://ethena.fi) wager.
The Sapience app generates a profile page for your account and ranks your profit/loss on the [leaderboard](https://sapience.xyz/leaderboard).
:::info
**We strongly recommend** using Cursor, Codex, Claude Code, or any other LLM-powered code editor. You may be surprised by how far you can get without writing code yourself. [See Get Started](/builder-guide/getting-started/get-started)
:::
## Prediction Market Trading Bots
This guide builds on the [Forecasting Agent](/builder-guide/guides/forecasting-agent) guide. Here, we'll add automated spot trading on individual markets using $1 wagers.
### Enable Spot Trading
To enable automatic spot trades on individual markets based on your forecasts:
```bash
# Enable spot trading feature
ENABLE_SPOT_TRADING=true
# Configure trade parameters (optional)
WAGER_AMOUNT=1000000000000000000 # $1 in USDe (18 decimals)
MIN_TRADING_CONFIDENCE=0.6 # Only trade with >60% confidence
MAX_TRADING_SLIPPAGE=5 # Maximum 5% slippage
```
**Key Differences from Multi-Leg Positions:**
* Trades on **individual markets** rather than multi-leg combinations
* **No minimum market requirement** - can trade with just 1 confident prediction
* Uses the **Quoter API** to size positions for exact dollar amounts
**Implementation:** [View spot trading code →](https://github.com/sapiencexyz/sapience/blob/main/starters/elizaos/src/actions/spotTradingAction.ts)
### Custom Trading Implementation
If you want to build your own trading logic beyond the built-in spot trading:
#### Dollar Wager Pattern
The bot uses a **Quoter API + Contract Call** pattern for exact dollar amounts:
1. **Query the Quoter API** to get position size for your target wager amount
2. **Call the contract** with the calculated position size and slippage protection
**Key files:**
* [Dollar wager implementation →](https://github.com/sapiencexyz/sapience/blob/main/starters/elizaos/src/actions/spotTradingAction.ts)
* [Quoter API usage →](https://github.com/sapiencexyz/sapience/blob/main/starters/elizaos/src/utils/contracts.ts)
#### Integration Points
To wire custom trading into your agent:
* **Add to action registry** in `src/index.ts`
* **Call from forecast loop** with confidence thresholds
* **Use existing blockchain utilities** from the starter for wallet management
***
### Advanced: Custom Limit Orders
For more sophisticated trading strategies, you can implement limit orders that wait for specific price targets:
**Example approach:**
* Monitor current market prices via polling or WebSocket
* Execute trades only when price reaches your target level
* Use the same Quoter API + Contract Call pattern as spot trading
**Implementation reference:** [View limit order example →](https://github.com/sapiencexyz/sapience/blob/main/starters/elizaos/src/actions/limitOrder.ts)
## Get Started
If you already have some programming experience, [skip ahead](/builder-guide/guides/forecasting-agent).
This guide walks you through setting up an AI-powered code editor and creating recommended accounts. You can then customize existing code or build your own project from scratch.
### Cursor Setup
[Cursor](https://cursor.com) is a modern, AI-powered IDE with a free plan available. Also consider using [Codex](https://chatgpt.com/codex), [Claude Code](https://www.claude.com/product/claude-code), and [v0](https://v0.app/).
#### Add Docs
Allow your assistant to read these docs too.
1. Press `Cmd+K` (or open the palette) and type `@Docs`, or go to Settings → Features → Docs
2. Choose "Add doc"
3. Enter `https://docs.sapience.xyz/` as the URL
4. Name it "Sapience" and save to index
5. Use in prompts: `@Docs Sapience`
#### Add Tools
Attaching the MCP server gives your editor tools that allow it to interact with Sapience's API directly. Learn more about the MCP server at [/builder-guide/api/mcp](/builder-guide/api/mcp).
1. Open Cursor → Settings → Cursor Settings → Tools & MCP → Add new MCP server
2. Paste the following configuration and save:
```json
{
"mcpServers": {
"sapience": {
"command": "npx",
"args": ["mcp-remote", "https://api.sapience.xyz/mcp"]
}
}
}
```
* Note this requires Node.js on your PATH so `npx` is available. (Ask an AI to help if you don't know what this means.)
* After saving, restart Cursor if tools do not appear.
### Ethereum Account Setup
You'll need an Ethereum wallet to interact with Sapience markets.
#### Private Key Generation
You can use a wallet app or generate one locally for development.
* **MetaMask**: [Download browser extension](https://metamask.io/download/)
* **Rainbow**: [Download mobile app](https://rainbow.me/)
* **Coinbase Wallet**: [Download](https://www.coinbase.com/wallet)
To generate a random private key from your terminal:
```bash
# Using OpenSSL (32 bytes -> 64 hex chars)
openssl rand -hex 32
# Or with Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
To derive the wallet address from a private key:
```bash
# Using Foundry (cast)
cast wallet address --private-key 0xYOUR_PRIVATE_KEY
# Or with Node.js + ethers v5 (ethers must be installed)
PRIVATE_KEY=0xYOUR_PRIVATE_KEY node -e "const { Wallet } = require('ethers'); console.log(new Wallet(process.env.PRIVATE_KEY).address)"
```
For development and testing:
1. Create a new wallet
2. Save your seed phrase or private key securely
3. Do not reuse this wallet for production
:::warning
Never share your private keys or seed phrase. Use separate wallets for development and production.
:::
#### Wallet Funding
You'll need ETH on **[Arbitrum](https://arbitrum.io/)** to pay gas fees for submitting forecasts. You can use [Coinbase](https://www.coinbase.com/) or other centralized exchanges to buy ETH and withdraw to the `Arbitrum One` network.
For trading on Sapience markets, you'll also need **USDe** on **Ethereal** for both gas and trading collateral. Visit [ethereal.trade](https://ethereal.trade) to bridge assets to Ethereal.
### Git Setup
If you don't already have a GitHub account, create one at [github.com](https://github.com/signup). Then, [download GitHub for Desktop](https://desktop.github.com/download/).
GitHub is essential for:
* Version control of your code
* Collaborating with others
* Deploying your applications
### OpenRouter Setup
OpenRouter provides access to multiple AI models for your applications.
1. Go to [OpenRouter](https://openrouter.ai/)
2. Sign up for an account
3. Navigate to your API keys
4. Create a new API key for your project
5. Store the key securely in your environment variables
You can use OpenRouter to integrate AI capabilities into your Sapience-powered applications.
### Railway Setup
Railway makes it easy to deploy apps and agents with one-click deployment.
**Quick Start**: Deploy a forecasting agent instantly using the [Deploy a Forecasting Agent](/builder-guide/guides/forecasting-agent) guide.
For manual setup:
* Visit [railway.com](https://railway.com/) and create an account
* Create a new project and connect your GitHub repo
* Set environment variables in the project settings (see [Forecasting Agent environment variables](/builder-guide/guides/forecasting-agent#environment-variables) for reference)
* Deploy your services and verify healthchecks
## Auction Relayer API
The Auction Relayer is a WebSocket service that facilitates real-time matching between **requesters** and **responders** for prediction market positions.
* **Requester**: Creates an auction by specifying a wager and predictions (including one or many picks). Referred to as `taker` in payloads.
* **Responder**: Submits bids offering to take the opposite side. Referred to as `maker` in payloads.
The relayer validates messages, broadcasts auctions to all connected clients, and streams bids to subscribed requesters.
### Endpoint
```
wss://relayer.sapience.xyz/auction
```
This is the standard relayer deployment. You can configure a different relayer in the app at [sapience.xyz/settings](https://sapience.xyz/settings).
### Message Flow
```
Requester Relayer Responder
│ │ │
│─── auction.start ────────▶│ │
│◀── auction.ack ───────────│ │
│ │─── auction.started ───────▶│
│ │ │
│ │◀── bid.submit ─────────────│
│ │─── bid.ack ───────────────▶│
│◀── auction.bids ──────────│ │
│ │ │
```
1. Requester sends `auction.start` with wager and picks
2. Relayer responds with `auction.ack` (includes `auctionId` and optional `id` if provided) and broadcasts `auction.started` to all clients
3. Responders send `bid.submit` with their wager offer and signature
4. Relayer replies `bid.ack` and streams `auction.bids` to the requester
Requesters are auto-subscribed to their auction's bid stream.
### Quick Start
#### Requester: Start an Auction
**Basic example (without signature):**
```ts
import WebSocket from 'ws';
const ws = new WebSocket('wss://relayer.sapience.xyz/auction');
// Initialize an auction
ws.on('open', () => {
ws.send(JSON.stringify({
type: 'auction.start',
payload: {
taker: '0xRequesterAddress...',
wager: '1000000000000000000', // 1 USDe in wei
resolver: '0xResolverContract...',
predictedOutcomes: ['0xEncodedPick1', '0xEncodedPick2'],
takerNonce: 1,
chainId: 42161
}
}));
});
```
**With signature (required by some market makers like the vault to respond with actionable bids):**
```ts
import WebSocket from 'ws';
import {
createAuctionStartSiweMessage,
extractSiweDomainAndUri
} from '@sapience/sdk';
import { privateKeyToAccount } from 'viem/accounts';
const ws = new WebSocket('wss://relayer.sapience.xyz/auction');
const account = privateKeyToAccount('0xYourPrivateKey...');
ws.on('open', async () => {
const payload = {
taker: account.address,
wager: '1000000000000000000',
resolver: '0xResolverContract...',
predictedOutcomes: ['0xEncodedPick1', '0xEncodedPick2'],
takerNonce: 1,
chainId: 42161
};
// Generate SIWE signature
const { domain, uri } = extractSiweDomainAndUri('wss://relayer.sapience.xyz/auction');
const issuedAt = new Date().toISOString();
const message = createAuctionStartSiweMessage(payload, domain, uri, issuedAt);
const signature = await account.signMessage({ message });
ws.send(JSON.stringify({
type: 'auction.start',
payload: {
...payload,
takerSignature: signature,
takerSignedAt: issuedAt
}
}));
});
// Listen for bids
ws.on('message', (data) => {
const msg = JSON.parse(String(data));
if (msg.type === 'auction.ack') {
console.log('Auction started:', msg.payload.auctionId);
}
if (msg.type === 'auction.bids') {
const bids = msg.payload.bids;
// Filter out quote-only bids (zero address/signature) and expired bids
const actionableBids = bids.filter(b => {
return b.maker !== '0x0000000000000000000000000000000000000000' &&
b.makerSignature !== '0x0000000000000000000000000000000000000000000000000000000000000000' &&
b.makerDeadline > Date.now() / 1000;
});
// Select best bid by highest makerWager
actionableBids.sort((a, b) => BigInt(b.makerWager) > BigInt(a.makerWager) ? 1 : -1);
console.log('Best actionable bid:', actionableBids[0]);
}
});
```
#### Responder: Submit a Bid
```ts
const ws = new WebSocket('wss://relayer.sapience.xyz/auction');
// Listen for bids
ws.onmessage = (ev) => {
const msg = JSON.parse(String(ev.data));
if (msg.type === 'auction.started') {
const auction = msg.payload;
const now = Math.floor(Date.now() / 1000);
ws.send(JSON.stringify({
type: 'bid.submit',
payload: {
auctionId: auction.auctionId,
maker: '0xResponderAddress...',
makerWager: (BigInt(auction.wager) / 2n).toString(),
makerDeadline: now + 60,
makerSignature: '0x...', // EIP-712 typed signature
makerNonce: 1
}
}));
}
};
```
### Payloads
#### `auction.start`
```ts
{
type: 'auction.start',
id?: string, // Optional request ID for correlation
payload: {
taker: string, // Requester's address (0x...) - EOA or smart account
wager: string, // Wager amount in wei
resolver: string, // Resolver contract address
predictedOutcomes: string[], // Encoded picks (bytes strings)
takerNonce: number,
chainId: number,
takerSignature?: string, // Optional: EIP-191 signature of the taker (SIWE format)
takerSignedAt?: string, // Optional: ISO timestamp when signature was created (required if takerSignature is provided)
sessionApproval?: string, // ZeroDev session approval (base64) for smart account auth
sessionTypedData?: object // EIP-712 typed data (required when sessionApproval is provided)
}
}
```
If `id` is provided, it will be echoed back in the `auction.ack` response for client-side correlation.
**Signature Requirements:**
* `takerSignature` and `takerSignedAt` are **optional** fields
* **Unsigned requests**: Used for price discovery/quoting only. Market makers may respond with quote-only bids (see below)
* **Signed requests**: Required by some market makers (like the vault) to respond with actionable, signed bids that can be executed on-chain
* When provided, the relayer verifies the signature to ensure the requester authorized the auction request
* Use the SDK's `createAuctionStartSiweMessage` and `extractSiweDomainAndUri` helpers to generate the signature
**Smart Account Authentication:**
* For smart account users (ZeroDev Kernel accounts), the `sessionApproval` and `sessionTypedData` fields enable session-based authentication
* **Both fields are required together** - `sessionTypedData` must be provided when using `sessionApproval`
* The `sessionApproval` is a base64-encoded ZeroDev permission account (with private key stripped for security)
* The `sessionTypedData` contains the EIP-712 typed data that was signed during session creation
* This allows the relayer to verify smart account ownership without on-chain RPC calls
* The relayer recovers the owner from the enable signature and verifies the smart account address matches
#### `bid.submit`
```ts
{
type: 'bid.submit',
payload: {
auctionId: string,
maker: string, // Responder's address - EOA or smart account
makerWager: string, // Responder's wager in wei
makerDeadline: number, // Unix timestamp (must be future)
makerSignature: string, // EIP-712 signature
makerNonce: number
}
}
```
**Note:** The `makerSignature` is verified on-chain when the taker accepts the bid and calls `mint()`. The relayer performs structural validation only.
#### `auction.bids`
Streamed to auction subscribers:
```ts
{
type: 'auction.bids',
payload: {
auctionId: string,
bids: Array<{
auctionId: string,
maker: string,
makerWager: string,
makerDeadline: number,
makerSignature: string,
makerNonce: number
}>
}
}
```
**Quote-only vs Actionable Bids:**
* **Quote-only bids**: When `maker` is `0x0000000000000000000000000000000000000000` and `makerSignature` is `0x0000...` (all zeros), this indicates a price quote only, not an actionable bid that can be executed on-chain. These are typically returned in response to unsigned auction requests.
* **Actionable bids**: When `maker` is a valid address and `makerSignature` is a real signature, the bid can be accepted and executed on-chain. These are returned in response to signed auction requests (required by some market makers like the vault).
### Validation
**Auction** (`auction.start`):
* `predictedOutcomes` has ≥1 non-empty bytes string
* `taker` is a valid address
* `resolver` is provided
* If `takerSignature` is provided, it must be a valid EIP-191 signature and `takerSignedAt` must be provided
* If signature verification fails, the relayer returns `error: 'invalid_signature'` or `error: 'signature_verification_failed'`
**Bid** (`bid.submit`):
* `auctionId` matches an active auction
* `makerWager` > 0
* `makerDeadline` is in the future
* `makerSignature` is valid hex format
### Smart Account Authentication
The relayer supports ZeroDev Kernel smart accounts with session-based authentication for **auction requesters** (takers). This allows requesters to create a session once and submit multiple auction requests without signing each one individually with their wallet.
**Note:** Bid signatures (`makerSignature`) are not verified by the relayer. They are verified on-chain when the taker accepts a bid.
#### Authentication Flow
The relayer uses a 3-path verification strategy:
1. **Session Approval Path** (for `auction.start` only): If `sessionApproval` and `sessionTypedData` are provided:
* Parse the base64-encoded approval to extract the enable signature
* Use the provided typed data to recover the owner who authorized the session
* Compute the expected smart account address from the recovered owner
* Verify it matches the claimed `taker` address
* Extract the authorized session key from the signed `validatorData`
* Verify the request signature (`takerSignature`) was signed by that authorized session key
2. **EOA Path**: Try direct signature verification against the address (works for EOAs)
3. **Smart Account Owner Path**: If EOA verification fails:
* Recover the signer from the signature
* Compute their smart account address
* Verify it matches the claimed address
#### Security Properties
* **No RPC calls**: All verification is deterministic using CREATE2 address computation
* **One-time session signature**: Users sign once during session creation; the enable signature proves ownership
* **Counterfactual accounts**: Works even for smart accounts that haven't been deployed yet
* **Unspoofable**: The smart account address is deterministically derived from the owner's EOA
* **Session key extraction**: The authorized session key is extracted from the cryptographically signed `validatorData`, not from client-provided data. This prevents attackers from claiming authorization for arbitrary session keys
#### Session Typed Data Structure
The `sessionTypedData` object has the following structure:
```ts
{
domain: {
name: 'Kernel',
version: '0.3.1',
chainId: number,
verifyingContract: string // Smart account address
},
types: {
Enable: [
{ name: 'validationId', type: 'bytes21' },
{ name: 'nonce', type: 'uint32' },
{ name: 'hook', type: 'address' },
{ name: 'validatorData', type: 'bytes' },
{ name: 'hookData', type: 'bytes' },
{ name: 'selectorData', type: 'bytes' }
]
},
primaryType: 'Enable',
message: {
validationId: string, // Hex
nonce: number,
hook: string, // Address
validatorData: string, // Hex
hookData: string, // Hex
selectorData: string // Hex
}
}
```
This typed data is captured during session creation and must be included with requests for reliable verification.
### Additional Messages
#### auction.subscribe
Subscribe to an existing auction's bid stream without starting a new auction:
```ts
{
type: 'auction.subscribe',
payload: {
auctionId: string
}
}
```
This is useful when a secondary client needs to monitor bids for an auction started by another connection.
### Connection Limits
* **Rate limit**: 100 messages per 10 seconds. Exceeding closes connection with code `1008`.
* **Message size**: Max 64KB per message. Exceeding closes connection with code `1009`.
### Error Codes
Returned in `auction.ack.payload.error` or `bid.ack.payload.error`:
**Auction errors:**
* `invalid_signature` – Taker signature verification failed
* `signature_verification_failed` – Error during signature verification process
**Session authentication errors:**
* `typed_data_required` – `sessionTypedData` must be provided when using `sessionApproval`
* `chain_id_mismatch` – Chain ID in payload doesn't match typed data domain
* `verifying_contract_mismatch` – Typed data verifyingContract doesn't match claimed address
* `account_mismatch` – Account address in approval doesn't match claimed address
* `owner_mismatch` – Recovered owner's smart account doesn't match claimed address
**Bid errors:**
* `invalid_payload` – Malformed message structure
* `auction_not_found_or_expired` – Unknown or expired auction
* `quote_expired` – `makerDeadline` has passed
* `invalid_maker_wager` – Wager is zero or invalid
* `invalid_maker` – Maker address is invalid
* `invalid_maker_bid_signature_format` – Signature format invalid
### Bid Acceptance
After selecting a bid, the requester constructs a `MintParlayRequestData` struct and calls `mint()` on the PredictionMarket contract. Both parties must have ERC-20 approvals set for the contract to pull their collateral (USDe).
Reference implementation: `packages/api/src/auction/botExample.ts`
## GraphQL API
### Sandbox
Explore the API and discover available queries, mutations, and types in the interactive sandbox: **[api.sapience.xyz/graphql](https://api.sapience.xyz/graphql)**
The sandbox includes full schema documentation, autocomplete, and lets you run queries directly in your browser.
### Endpoint
```
https://api.sapience.xyz/graphql
```
### TypeScript Types
The SDK exports all GraphQL types for use in your TypeScript projects:
```typescript
import type {
Category
} from '@sapience/sdk';
```
View the full type definitions on GitHub: [packages/sdk/types/graphql.ts](https://github.com/foilxyz/foil/blob/main/packages/sdk/types/graphql.ts)
### Quick Example
```typescript
import { ApolloClient, InMemoryCache, gql } from '@apollo/client';
const client = new ApolloClient({
uri: 'https://api.sapience.xyz/graphql',
cache: new InMemoryCache()
});
const { data } = await client.query({
query: gql`
query GetCategories {
categories {
id
name
}
}
`
});
data.categories.forEach(category => {
console.log(category.name);
});
```
### Notes
* APIs are currently public; please be considerate and cache when possible
* Pagination is supported via `first`, `skip`, `orderBy`, `orderDirection`
## Model Context Protocol (MCP)
### What is MCP?
MCP is an open standard for connecting AI applications to external data sources and tools. It lets AI assistants like Claude or ChatGPT access live data and perform actions on your behalf.
Learn more at **[modelcontextprotocol.io](https://modelcontextprotocol.io/)**
### Endpoint
```
https://api.sapience.xyz/mcp
```
Connect any [MCP client](https://modelcontextprotocol.io/clients) to query open questions, explore existing positions, generate calldata for blockchain transactions, and more.
### Quick Setup
Add to Claude Desktop or Cursor via `mcp-remote`:
```json
{
"mcpServers": {
"sapience": {
"command": "npx",
"args": ["mcp-remote", "https://api.sapience.xyz/mcp"]
}
}
}
```
No authentication required. Please be considerate; rate limiting may apply.
## Quoter API
The Quoter API determines the largest position size that can be opened with a given amount of collateral while respecting target price constraints. It performs a bounded binary search against on-chain quoting to find a feasible, direction-aware size.
### Endpoint
* Production: `https://api.sapience.xyz/quoter` (confirm base URL)
* Local (monorepo): `http://localhost:3001/quoter`
#### GET `/:chainId/:marketAddress/:marketId`
Returns the maximum feasible position size for the specified market and target price, within the provided collateral budget.
##### Path parameters
* `chainId`: Number. Chain ID where the market group is deployed.
* `marketAddress`: String. Market group contract address (`0x...`).
* `marketId`: Number. Market ID within the group.
##### Query parameters
* `expectedPrice` (required): Decimal string. Target reference price after the trade.
* `collateralAvailable` (required): Wei string. Collateral budget available for the position.
* `maxIterations` (optional): Integer 1–10. Bounded binary search iterations (default: 10; max: 10).
* `priceLimit` (optional): Decimal string. Price guardrail; defaults to current reference price.
* For LONG: fill price must be `> priceLimit` and `<= expectedPrice`.
* For SHORT: fill price must be `< priceLimit` and `>= expectedPrice`.
##### Response
```typescript
type QuoteResponse = {
direction: 'LONG' | 'SHORT';
maxSize: string; // signed wei string: LONG > 0, SHORT < 0
currentPrice: string; // decimal string
expectedPrice: string; // decimal string
collateralAvailable: string // wei string
}
```
Notes:
* `direction` is inferred from `expectedPrice` vs current reference price.
* `maxSize` is signed: positive for LONG, negative for SHORT. Its absolute value is the largest feasible size given constraints.
* All numeric values are strings to preserve precision.
### Examples
#### Basic
```bash
curl "http://localhost:3001/quoter/1/0x1234000000000000000000000000000000005678/1?expectedPrice=1000&collateralAvailable=1000000000000000000"
```
Example response
```json
{
"direction": "LONG",
"maxSize": "500000000000000000",
"currentPrice": "950",
"expectedPrice": "1000",
"collateralAvailable": "1000000000000000000"
}
```
#### With price limit and custom iterations
```bash
curl "http://localhost:3001/quoter/1/0x1234000000000000000000000000000000005678/1?expectedPrice=1000&collateralAvailable=1000000000000000000&priceLimit=980&maxIterations=5"
```
### Errors
The API returns structured errors with appropriate HTTP status codes:
* 400 Bad Request
* `Invalid query parameters` (validation details included)
* `Expected price must be greater than 0`
* `Expected price must be different from current price`
* `Could not find a valid position size that satisfies the price constraints`
* `Insufficient liquidity. Try a smaller size.`
* 404 Not Found
* `Market not found`
* `Current price not found`
* 500 Internal Server Error
### Implementation details
* The service reads the current reference price from `getReferencePrice(marketId)`.
* It runs a binary search (up to `maxIterations`, capped at 10) between zero and a theoretical cap derived from `collateralAvailable / currentPrice`.
* Feasibility at each step is checked by simulating `quoteCreateTraderPosition(marketId, signedSize)` on the market group contract.
* If the requested budget exceeds the feasible capacity at the price constraints, the service returns `400` with "Insufficient liquidity. Try a smaller size."
