Trade

Submit a new market order or limit order for execution.

POST /markets/trade

Trade

cURL

curl --request POST \
  --url https://www.aionmarket.com/bvapi/markets/trade \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "marketConditionId": "0xf64f880b571d7a70d858649d30f0843aa57307e304aeb617349df74ce34d044e",
  "marketQuestion": "Will Crude Oil (CL) hit (HIGH) $120 by end of March?",
  "outcome": "YES",
  "orderSize": 1,
  "price": 0.54,
  "order": {
    "maker": "0x1111111111111111111111111111111111111111",
    "signer": "0x1111111111111111111111111111111111111111",
    "tokenId": "69136365945621600854789649488423522395843457249417452310260493085275775221076",
    "makerAmount": "120000",
    "takerAmount": "1000000",
    "side": "BUY",
    "signature": "0x1234abcd",
    "salt": 599228746038,
    "signatureType": 0,
    "taker": "0x0000000000000000000000000000000000000000",
    "expiration": "0",
    "nonce": "0",
    "feeRateBps": "0",
    "timestamp": "1713000000000",
    "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "builder": "0x0000000000000000000000000000000000000000000000000000000000000000"
  },
  "venue": "polymarket",
  "isLimitOrder": true,
  "orderType": "GTC",
  "walletAddress": "<string>",
  "owner": "<string>",
  "deferExec": false,
  "orderVersion": 1,
  "tickSize": "0.1",
  "negRisk": false,
  "funderAddress": "<string>",
  "postOnly": false,
  "feeAmount": 0,
  "reasoning": "<string>",
  "source": "<string>",
  "skillSlug": "<string>",
  "expirationTime": 0
}
'

200

{
  "orderId": "<string>",
  "status": "<string>",
  "submittedAt": "2023-11-07T05:31:56Z"
}

Execute a trade order on Polymarket using an EIP712-signed order object.

Overview

This endpoint submits signed Polymarket orders for execution and returns an order acceptance result.

For immediate BUY orders (FAK / FOK), Polymarket enforces precision constraints:

• makerAmount supports max 2 decimals
• takerAmount supports max 4 decimals

Because amounts are sent as 6-decimal micro-units, validate before submitting:

• makerAmount % 10000 == 0
• takerAmount % 100 == 0

Prerequisites

1. Agent must be registered via POST /agents/register
2. Wallet credentials registered via POST /wallet/credentials
3. EIP712-signed order from Polymarket CLOB library
4. Market context checked via GET /markets/context/:marketId (recommended)

Request fields

Field	Type	Required	Description
venue	string	No	Defaults to polymarket
marketConditionId	string	Yes	Condition identifier
marketQuestion	string	Yes	Market question
outcome	string	Yes	YES or NO
orderSize	number	Yes	Requested contracts
price	number	Yes	Price per contract
isLimitOrder	boolean	No	Limit or market mode
orderType	string	No	GTC, FOK, GTD, FAK (default: GTC for limit, FAK for market)
walletAddress	string	No	Wallet address
orderVersion	integer	No	1=legacy V1, 2=Polymarket V2; auto-inferred if omitted
order	object	Yes	Signed EIP712 order payload
reasoning	string	No	Trade explanation
source	string	No	Strategy source tag
skillSlug	string	No	Skill identifier for attribution
expirationTime	number	No	Limit order expiration (milliseconds)
tickSize	string	No	V2 tick size: 0.1, 0.01, 0.001, 0.0001
negRisk	boolean	No	V2 market context flag
funderAddress	string	No	V2 funder address
postOnly	boolean	No	Post-only order flag
deferExec	boolean	No	Defer execution flag
owner	string	No	Polymarket owner (default uses wallet credential apiKey)
feeAmount	number	No	Market order fee (isLimitOrder=false only)

Examples

curl

curl -X POST https://www.aionmarket.com/bvapi/markets/trade \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "venue": "polymarket",
    "marketConditionId": "0xabc123...",
    "marketQuestion": "Will Bitcoin reach $100k by end of 2024?",
    "outcome": "YES",
    "orderSize": 10,
    "price": 0.68,
    "isLimitOrder": true,
    "walletAddress": "0x1111111111111111111111111111111111111111",
    "orderVersion": 2,
    "owner": "f4f247b7-4ac7-ff29-a152-04fda0a8755a",
    "orderType": "GTC",
    "deferExec": false,
    "postOnly": false,
    "order": {
      "maker": "0x1111111111111111111111111111111111111111",
      "signer": "0x1111111111111111111111111111111111111111",
      "taker": "0x0000000000000000000000000000000000000000",
      "tokenId": "0x123",
      "makerAmount": "6800000",
      "takerAmount": "10000000",
      "side": "BUY",
      "expiration": "1713604800",
      "timestamp": "1713000000000",
      "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "signature": "0x...",
      "salt": 1,
      "signatureType": 3
    },
    "feeAmount": 0,
    "reasoning": "Technical analysis shows bullish trend; RSI at 65",
    "source": "sdk:weather-alpha",
    "skillSlug": "polymarket-weather-trader",
    "expirationTime": 0
  }'

Python SDK

from aion_sdk import AionMarketClient

client = AionMarketClient(api_key="YOUR_API_KEY", base_url="https://www.aionmarket.com/bvapi")

signed_order = {
    "maker": "0xYOUR_WALLET",
    "signer": "0xYOUR_WALLET",
    "taker": "0x0000000000000000000000000000000000000000",
    "tokenId": "0xTOKEN_ID",
    "makerAmount": "6100000",
    "takerAmount": "10000000",
    "side": "BUY",
    "expiration": "1713604800",
    "timestamp": "1713000000000",
    "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "signature": "0x...",
    "salt": 1,
    "signatureType": 3,
}

result = client.trade({
    "venue": "polymarket",
    "marketConditionId": "0xabc123...",
    "marketQuestion": "Will Bitcoin reach $100k by end of 2024?",
    "outcome": "YES",
    "orderSize": 10,
    "price": 0.68,
    "isLimitOrder": True,
    "orderType": "GTC",
    "walletAddress": "0xYOUR_WALLET",
    "order": signed_order,
    "reasoning": "Positive edge after context check",
    "source": "sdk:strategy-alpha",
})
print(result)

Order Object (EIP712 Signed)

Required fields inside order:

Field	Type	Required	Description
maker	string	Yes	Maker wallet address
signer	string	Yes	Signing wallet address
taker	string	Yes	Taker address, usually zero address for open orders
tokenId	string	Yes	Polymarket CLOB token ID
makerAmount	string	Yes	Maker amount in 6-decimal integer precision
takerAmount	string	Yes	Taker amount in 6-decimal integer precision
side	string	Yes	BUY or SELL
expiration	string	Yes	Expiration timestamp in seconds
nonce	string	Yes (V1 only)	Unique nonce
feeRateBps	string	Yes (V1 only)	Fee rate in basis points
signature	string	Yes	EIP712 signature
salt	number	Yes	Random salt
signatureType	integer	Yes	0=EOA, 1=PolymarketProxy, 2=GnosisSafe, 3=POLY_1271
timestamp	string	Yes (V2 only)	Unix timestamp in milliseconds
metadata	string	Yes (V2 only)	V2 metadata (bytes32 hex)
builder	string	Yes (V2 only)	V2 builder (bytes32 hex)

Response

{
  "success": true,
  "orderId": "0x456def...",
  "status": "live",
  "orderVersion": 2,
  "collateralSymbol": "pUSD",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "signatureType": 3,
  "aiAgentId": "1",
  "userId": "42",
  "syncedToMkOrder": true,
  "syncedToStrategyLog": true
}

Common errors

Code	Meaning
400	Invalid payload, bad market/outcome, or invalid order object
401	Invalid API key
429	Rate limited
500	Server-side failure

Error Handling

Common response codes:

• 201: Request accepted (use response body success to determine downstream execution result)
• 400: Invalid market/outcome or insufficient balance
• 401: Invalid API key or expired
• 429: Rate limited
• 500: Server error

Pre-Trade Checklist

Before placing trade orders:

1. Get Market Context

   GET /markets/context/:marketId?user=YOUR_WALLET
   

2. Check Risk Warnings

   • Review suggested thresholds
   • Check position limits
   • Verify daily trade quota

3. Verify Market Status

   • Market must be active
   • Resolution date must not have passed
   • Sufficient liquidity

4. Sign Order

   • Use EIP712 signing
   • Verify expiration time
   • Double-check amounts

5. Execute Trade

   • Submit signed order
   • Monitor for fill status
   • Log reasoning for audit

Related Endpoints

• GET /markets/context/:marketId - Pre-trade risk analysis
• GET /markets/orders/open - Monitor pending orders
• POST /markets/orders/cancel - Cancel unfilled orders
• GET /agents/me - Check daily trade quota used
• POST /markets/redeem - Claim rewards on settled markets

Best Practices

• Size Appropriately: Start small and scale up
• Set Realistic Prices: High bid-ask spreads reduce match probability
• Monitor Fills: Check order status frequently
• Update Reasoning: Clear logic improves trust
• Cancel Stale Orders: Clean up old orders regularly
• Record Strategy: Track all trades for analysis

Authorizations

Authorization · string · header · default: YOUR_API_KEY · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

marketConditionId · string · required

Market conditionId (persisted to mk_order)

Example:

"0xf64f880b571d7a70d858649d30f0843aa57307e304aeb617349df74ce34d044e"

marketQuestion · string · required

Market question (persisted to mk_order)

Maximum string length: 250

Example:

"Will Crude Oil (CL) hit (HIGH) $120 by end of March?"

outcome · enum<string> · required

Outcome direction

Available options: YES, NO

orderSize · number · required

Order size (contracts), persisted to mk_order.orderSize

Example:

1

price · number · required

Order price per contract, persisted to mk_order.price

Example:

0.54

order · object · required

Show child attributes

venue · string · default: polymarket

Trading venue (default polymarket)

Maximum string length: 50

isLimitOrder · boolean · default: true

true=createOrder (limit); false=createMarketOrder (market)

orderType · enum<string> · default: GTC

Order type (default GTC for limit, FAK for market)

Available options: GTC, FOK, GTD, FAK

walletAddress · string

Wallet address (optional; falls back to order.signer)

Pattern: ^0x[a-fA-F0-9]{40}$

owner · string

Polymarket owner (optional, defaults to apiKey from credentials)

Maximum string length: 128

deferExec · boolean · default: false

Defer execution flag

orderVersion · enum<integer>

Order version: 1=legacy V1, 2=Polymarket V2 (auto-inferred when omitted)

Available options: 1, 2

tickSize · enum<string>

V2 tickSize hint

Available options: 0.1, 0.01, 0.001, 0.0001

negRisk · boolean · default: false

V2 negRisk flag

funderAddress · string

V2 funder address (optional)

Pattern: ^0x[a-fA-F0-9]{40}$

postOnly · boolean · default: false

Post-only flag

feeAmount · number · default: 0

Market-order fee (only when isLimitOrder=false)

reasoning · string

Trade reasoning text (max 1000 chars)

Maximum string length: 1000

source · string

Source tag (suggested format sdk:strategy-name)

Maximum string length: 100

skillSlug · string

Skill identifier for attribution

Maximum string length: 100

expirationTime · number · default: 0

Limit order expiration in milliseconds (mk_order.expirationTime)

Response

200 - application/json

Trade accepted

orderId · string

status · string

submittedAt · string<date-time>