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

​
Usage

result = client.buy(
    token_id="your-token-id",
    shares=10,
    price=0.55,
    order_type="GTC"  # Optional, defaults to GTC
)
For market orders that execute immediately, use market_buy() instead.

​
Parameters

​
token_id
string
required
The outcome token ID to buy.
​
shares
number
required
Number of shares to buy.
​
price
number
required
Limit price per share (0.01 - 0.99).
​
order_type
string
default:"GTC"
Order type:
  • GTC - Good Till Cancelled (limit order, sits on book)
  • FOK - Fill Or Kill (must fully fill immediately or cancel)
  • FAK - Fill And Kill (fills immediately, cancels unfilled)

​
Response

​
order_id
string
The created order ID.
​
status
string
Order status after placement.
​
message
string
Status message.
​
warning
string
Warning message, if any (e.g., partial fill warning).
​
latency_ms
number
Order execution latency in milliseconds.

​
Example

from polyhush import PolyhushClient, PolyhushAPIError

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

try:
    result = client.buy(
        token_id="12345678901234567890",
        shares=100,
        price=0.55,
        order_type="GTC"
    )
    
    print(f"Order placed: {result['order_id']}")
    print(f"Status: {result['status']}")
    print(f"Latency: {result['latency_ms']}ms")
    
    if result.get('warning'):
        print(f"⚠️ Warning: {result['warning']}")
        
except PolyhushAPIError as e:
    print(f"Order failed: {e.message}")

​
Response

{
  "order_id": "ord_abc123",
  "status": "PLACED",
  "message": "Order placed successfully",
  "latency_ms": 45
}

​
Order Type Behavior

TypeBehavior
GTCOrder sits on book until filled or cancelled
FOKMust fill completely immediately or cancels
FAKFills what’s available, cancels rest
Use GTC orders to get better pricing by providing liquidity. Use FAK (via market_buy()) when you need immediate execution.