Skip to main content
POST
/
api
/
v1
/
trading
/
orders
Market Buy
curl --request POST \
  --url https://api.example.com/api/v1/trading/orders \
  --header 'Content-Type: application/json' \
  --data '
{
  "token_id": "<string>",
  "usdc_amount": 123,
  "shares": 123
}
'
{
  "order_id": "<string>",
  "status": "<string>",
  "message": "<string>",
  "warning": "<string>",
  "latency_ms": 123
}

​
Usage

# Spend a specific USDC amount
result = client.market_buy(token_id="your-token-id", usdc_amount=50)

# Or buy a specific number of shares
result = client.market_buy(token_id="your-token-id", shares=100)
Market orders execute immediately at the best available prices. Use usdc_amount to spend a fixed amount, or shares to buy a specific quantity.

​
Parameters

​
token_id
string
required
The outcome token ID to buy.
​
usdc_amount
number
USDC amount to spend. Preferred - gives you precise control over cost.
​
shares
number
Number of shares to buy. Will be converted to USDC using the current market price.
Provide either usdc_amount OR shares, not both.

​
Response

​
order_id
string
The created order ID.
​
status
string
Order status (typically FILLED or CANCELLED for market orders).
​
message
string
Status message.
​
warning
string
Warning message, if any (e.g., partial fill due to liquidity).
​
latency_ms
number
Order execution latency in milliseconds.

​
Examples

​
Spend a fixed USDC amount

from polyhush import PolyhushClient

client = PolyhushClient(api_key="your-api-key")

# Spend exactly $50 on shares at market price
result = client.market_buy(
    token_id="12345678901234567890",
    usdc_amount=50
)

print(f"Order: {result['order_id']}")
print(f"Status: {result['status']}")

​
Buy a specific number of shares

# Buy 100 shares at market price
result = client.market_buy(
    token_id="12345678901234567890",
    shares=100
)

print(f"Bought shares, order: {result['order_id']}")

​
Response

{
  "order_id": "ord_mkt123",
  "status": "FILLED",
  "message": "Market order filled",
  "latency_ms": 52
}

​
How It Works

Market buy orders use the FAK (Fill And Kill) order type:
  1. The order is placed at a high price to ensure it fills
  2. It matches against existing sell orders on the book
  3. Whatever fills immediately is executed
  4. Any unfilled portion is cancelled
Using usdc_amount is recommended because:
  • You know exactly how much you’re spending
  • No need to calculate shares based on fluctuating prices
  • Better for budgeting and risk management

​
Slippage Considerations

Market orders may experience slippage if:
  • The order is large relative to available liquidity
  • The market is volatile
  • There’s a wide bid-ask spread
For large orders, consider using limit orders (buy()) to control your execution price.