Skip to main content
POST
/
v1
/
orders
{
  "success": true,
  "data": {
    "id": "<string>",
    "market_id": "<string>",
    "platform": "<string>",
    "side": "<string>",
    "type": "<string>",
    "status": "<string>",
    "amount": 123,
    "price": 123,
    "filled_amount": 123,
    "average_fill_price": 123,
    "fees": 123,
    "created_at": "<string>",
    "updated_at": "<string>"
  }
}

​
Submit Order

Place a new order on a prediction market. Orders are routed to the optimal platform automatically.
Trading requires authentication. You must have a connected wallet and funded Safe to submit orders.

​
Endpoint

POST https://api.matchr.xyz/v1/orders

​
Request Body

​
market_id
string
required
The market ID to trade on
​
side
string
required
Order side: buy or sell
​
type
string
required
Order type: market or limit
​
amount
number
required
Order amount in USD
​
price
number
Limit price (required for limit orders). Value between 0.01 and 0.99.
​
time_in_force
string
default:"GTC"
Time in force: GTC (Good Til Cancelled), IOC (Immediate or Cancel), FOK (Fill or Kill)
​
wallet_id
string
Specific wallet to use (optional, defaults to primary wallet)

​
Example Request

curl -X POST "https://api.matchr.xyz/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "mkt_yes123",
    "side": "buy",
    "type": "limit",
    "amount": 100,
    "price": 0.52
  }'

​
Response

​
success
boolean
Whether the order was submitted successfully
​
data
object
Order details

​
Example Response

{
  "success": true,
  "data": {
    "id": "ord_abc123",
    "market_id": "mkt_yes123",
    "platform": "polymarket",
    "side": "buy",
    "type": "limit",
    "status": "open",
    "amount": 100,
    "price": 0.52,
    "filled_amount": 0,
    "average_fill_price": null,
    "fees": 0,
    "created_at": "2024-10-15T14:35:00Z",
    "updated_at": "2024-10-15T14:35:00Z"
  }
}

​
Market Orders

Market orders execute immediately at the best available price. 
{
  "market_id": "mkt_yes123",
  "side": "buy",
  "type": "market",
  "amount": 100
}
Market orders may experience slippage if liquidity is thin. For large orders, consider using limit orders.

​
Limit Orders

Limit orders only execute at your specified price or better. 
{
  "market_id": "mkt_yes123",
  "side": "buy",
  "type": "limit",
  "amount": 100,
  "price": 0.50,
  "time_in_force": "GTC"
}

​
Time in Force Options

ValueDescription
GTCGood Til Cancelled - Order remains open until filled or cancelled
IOCImmediate or Cancel - Execute immediately; cancel unfilled portion
FOKFill or Kill - Execute entire order immediately or cancel entirely

​
Order Routing

Matchr automatically routes orders to the best platform based on:
  1. Price - Best available price across platforms
  2. Liquidity - Sufficient depth to fill the order
  3. Fees - Platform fee comparison
  4. Slippage - Expected price impact

​
Routing Override

Force an order to a specific platform: 
{
  "market_id": "mkt_yes123",
  "side": "buy",
  "type": "limit",
  "amount": 100,
  "price": 0.52,
  "platform": "polymarket"
}

​
Batch Orders

Submit multiple orders in a single request.

​
Endpoint

POST https://api.matchr.xyz/v1/orders/batch

​
Request Body

{
  "orders": [
    {
      "market_id": "mkt_yes123",
      "side": "buy",
      "type": "limit",
      "amount": 50,
      "price": 0.51
    },
    {
      "market_id": "mkt_yes123",
      "side": "buy",
      "type": "limit",
      "amount": 50,
      "price": 0.50
    }
  ]
}

​
Response

{
  "success": true,
  "data": {
    "submitted": 2,
    "failed": 0,
    "orders": [
      { "id": "ord_abc123", "status": "open" },
      { "id": "ord_abc124", "status": "open" }
    ]
  }
}

​
Error Codes

CodeDescription
400Invalid order parameters
401Missing or invalid API key
402Insufficient balance
403Trading not enabled for this account
404Market not found
409Market closed or suspended
422Order validation failed
429Rate limit exceeded
500Server error

​
Common Validation Errors

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient USDC balance",
    "details": {
      "required": 100,
      "available": 45.50
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_PRICE",
    "message": "Price must be between 0.01 and 0.99",
    "details": {
      "provided": 1.05
    }
  }
}