Pydantic Models

Overview

The SnipeRoute SDK uses Pydantic v2 models for type-safe request/response handling. All models provide:

Automatic validation
Type coercion
JSON serialization/deserialization
IDE auto-completion

Trade Intent Models

TradeIntentRequest

Model for creating a Trade Intent.

from sniperoute.models import TradeIntentRequest, OrderSide, OrderType, TimeInForce
from decimal import Decimal
 
intent = TradeIntentRequest(
    intent_id="trade_001",
    symbol="AAPL",
    side=OrderSide.BUY,
    quantity=Decimal("10"),
    order_type=OrderType.MARKET,
    broker_id="my_broker"
)

Fields:

Field	Type	Required	Description
`intent_id`	str	Yes	Unique identifier (idempotency key)
`symbol`	str	Yes	Trading symbol (e.g., "AAPL")
`side`	OrderSide	Yes	`OrderSide.BUY` or `OrderSide.SELL`
`quantity`	Decimal	Yes	Number of shares/units
`order_type`	OrderType	Yes	See OrderType
`broker_id`	str	Yes	Connected broker account ID
`limit_price`	Decimal \| None	Conditional	Required for limit orders
`stop_price`	Decimal \| None	Conditional	Required for stop orders
`time_in_force`	TimeInForce \| None	No	Default: `TimeInForce.DAY`
`extended_hours`	bool	No	Default: `False`

TradeIntentResponse

Model returned when creating or querying a Trade Intent.

response = await client.create_intent(intent)
 
print(f"ID: {response.id}")
print(f"Intent ID: {response.intent_id}")
print(f"Status: {response.status}")
print(f"Symbol: {response.symbol}")

Fields:

Field	Type	Description
`id`	str (UUID)	Internal Trade Intent UUID
`intent_id`	str	Your external identifier
`symbol`	str	Trading symbol
`side`	OrderSide	Order side
`quantity`	Decimal	Number of shares/units
`order_type`	OrderType	Order type
`limit_price`	Decimal \| None	Limit price (if applicable)
`stop_price`	Decimal \| None	Stop price (if applicable)
`time_in_force`	TimeInForce	Time in force
`extended_hours`	bool	Extended hours enabled
`status`	IntentStatus	Current status
`broker_id`	str	Broker account ID
`orders`	list[Order]	List of broker orders
`error`	ErrorDetail \| None	Error details (if failed)
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

Order Models

Order

Model representing a broker order.

for order in response.orders:
    print(f"Broker Order ID: {order.broker_order_id}")
    print(f"Status: {order.status}")

Fields:

Field	Type	Description
`id`	str (UUID)	Internal order UUID
`broker_order_id`	str	Broker's order ID
`status`	OrderStatus	Order status
`fills`	list[Fill]	List of fills
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

Fill

Model representing an order fill.

for fill in order.fills:
    print(f"Filled: {fill.quantity} @ ${fill.price}")
    print(f"Time: {fill.filled_at}")

Fields:

Field	Type	Description
`quantity`	Decimal	Shares filled
`price`	Decimal	Fill price
`filled_at`	datetime	Fill timestamp

Enums

OrderSide

from sniperoute.models import OrderSide
 
# Buy order
side = OrderSide.BUY
 
# Sell order
side = OrderSide.SELL

Values:

OrderSide.BUY - Buy order
OrderSide.SELL - Sell order

OrderType

from sniperoute.models import OrderType
 
# Market order
order_type = OrderType.MARKET
 
# Limit order
order_type = OrderType.LIMIT
 
# Stop order
order_type = OrderType.STOP
 
# Stop-limit order
order_type = OrderType.STOP_LIMIT

Values:

OrderType.MARKET - Market order
OrderType.LIMIT - Limit order
OrderType.STOP - Stop order
OrderType.STOP_LIMIT - Stop-limit order

TimeInForce

from sniperoute.models import TimeInForce
 
# Day order (default)
tif = TimeInForce.DAY
 
# Good-till-canceled
tif = TimeInForce.GTC
 
# Immediate-or-cancel
tif = TimeInForce.IOC
 
# Fill-or-kill
tif = TimeInForce.FOK

Values:

TimeInForce.DAY - Valid until end of trading day
TimeInForce.GTC - Good-till-canceled
TimeInForce.IOC - Immediate-or-cancel
TimeInForce.FOK - Fill-or-kill

IntentStatus

from sniperoute.models import IntentStatus
 
if response.status == IntentStatus.FILLED:
    print("Order filled!")

Values:

IntentStatus.PENDING - Order pending
IntentStatus.FILLED - Order fully filled
IntentStatus.PARTIALLY_FILLED - Order partially filled
IntentStatus.CANCELED - Order canceled
IntentStatus.REJECTED - Broker rejected
IntentStatus.FAILED - Routing/validation failed

OrderStatus

from sniperoute.models import OrderStatus
 
for order in response.orders:
    if order.status == OrderStatus.FILLED:
        print("Order filled!")

Values:

OrderStatus.PENDING - Order pending
OrderStatus.FILLED - Order fully filled
OrderStatus.PARTIALLY_FILLED - Order partially filled
OrderStatus.CANCELED - Order canceled
OrderStatus.REJECTED - Broker rejected

Error Models

ErrorDetail

Model for error information.

if response.error:
    print(f"Error code: {response.error.code}")
    print(f"Message: {response.error.message}")

Fields:

Field	Type	Description
`code`	str	Error code
`message`	str	Error message

Validation

Automatic Validation

Pydantic automatically validates all fields:

from sniperoute.models import TradeIntentRequest, OrderSide, OrderType
from decimal import Decimal
 
# This will raise ValidationError
intent = TradeIntentRequest(
    intent_id="trade_001",
    symbol="AAPL",
    side="invalid_side",  # Invalid enum value
    quantity=Decimal("10"),
    order_type=OrderType.MARKET,
    broker_id="my_broker"
)

Manual Validation

from pydantic import ValidationError
 
try:
    intent = TradeIntentRequest(...)
except ValidationError as e:
    print(e.errors())

JSON Serialization

To JSON

# Convert to dict
intent_dict = intent.model_dump()
 
# Convert to JSON string
import json
intent_json = json.dumps(intent.model_dump(), default=str)

From JSON

import json
from sniperoute.models import TradeIntentResponse
 
# Parse JSON
data = json.loads(response_json)
 
# Create model
response = TradeIntentResponse(**data)

Type Hints

All models have full type hints for IDE support:

from sniperoute.models import TradeIntentRequest
from decimal import Decimal
 
def create_market_order(
    symbol: str,
    quantity: Decimal,
    broker_id: str
) -> TradeIntentRequest:
    return TradeIntentRequest(
        intent_id=f"order_{symbol}",
        symbol=symbol,
        side=OrderSide.BUY,
        quantity=quantity,
        order_type=OrderType.MARKET,
        broker_id=broker_id
    )
 
# IDE will auto-complete fields
intent = create_market_order("AAPL", Decimal("10"), "my_broker")

Next Steps

Client Reference

SnipeRouteClient API

Error Handling

Exception hierarchy

Webhooks Error Handling