Trade Intents

Self-contained execution instructions for stateless routing.

Overview

A Trade Intent is a self-contained, fully specified instruction that contains all parameters required for execution. Trade Intents are the core primitive in SnipeRoute's stateless routing architecture.

Every Trade Intent is independent and complete. SnipeRoute does not maintain strategy state or context between intents.

Trade Intent Structure

Required Fields

Field	Type	Description
`intent_id`	string	Unique identifier from upstream platform (idempotency key)
`symbol`	string	Trading symbol (e.g., "AAPL", "TSLA")
`side`	string	Order side: `"buy"` or `"sell"`
`quantity`	number	Number of shares/units to trade
`order_type`	string	Order type: `"market"`, `"limit"`, `"stop"`, `"stop_limit"`
`broker_id`	string	ID of the user's connected broker account

Optional Fields

Field	Type	Required When	Description
`limit_price`	number	`order_type` is `"limit"` or `"stop_limit"`	Limit price for execution
`stop_price`	number	`order_type` is `"stop"` or `"stop_limit"`	Stop trigger price
`time_in_force`	string	Optional	`"day"`, `"gtc"`, `"ioc"`, `"fok"` (default: `"day"`)
`extended_hours`	boolean	Optional	Allow trading in extended hours (default: `false`)

Example Trade Intents

Market Buy Order

{
  "intent_id": "trade_001",
  "symbol": "AAPL",
  "side": "buy",
  "quantity": 10,
  "order_type": "market",
  "broker_id": "my_alpaca"
}

Limit Sell Order

{
  "intent_id": "trade_002",
  "symbol": "TSLA",
  "side": "sell",
  "quantity": 5,
  "order_type": "limit",
  "limit_price": 250.00,
  "time_in_force": "gtc",
  "broker_id": "my_schwab"
}

Stop-Limit Buy Order

{
  "intent_id": "trade_003",
  "symbol": "NVDA",
  "side": "buy",
  "quantity": 20,
  "order_type": "stop_limit",
  "stop_price": 500.00,
  "limit_price": 505.00,
  "time_in_force": "day",
  "broker_id": "my_ibkr"
}

Stateless Routing

SnipeRoute does not maintain state between Trade Intents:

No stored strategies
No position tracking
No portfolio context
No order dependencies

Each Trade Intent is processed independently.

Example: Independent Intents

# Intent 1: Buy 10 shares of AAPL
intent_1 = TradeIntentRequest(
    intent_id="trade_001",
    symbol="AAPL",
    side=OrderSide.BUY,
    quantity=Decimal("10"),
    order_type=OrderType.MARKET,
    broker_id="my_alpaca"
)
 
# Intent 2: Buy 5 more shares of AAPL
intent_2 = TradeIntentRequest(
    intent_id="trade_002",
    symbol="AAPL",
    side=OrderSide.BUY,
    quantity=Decimal("5"),
    order_type=OrderType.MARKET,
    broker_id="my_alpaca"
)
 
# Intent 2 does NOT depend on Intent 1
# SnipeRoute does not aggregate or optimize across intents
# Each is routed independently to the broker

Idempotency

The intent_id field serves as an idempotency key. If you submit the same intent_id twice, SnipeRoute will:

Accept the first submission
Reject the second submission with 409 Conflict

This prevents accidental duplicate orders.

Example: Idempotent Submission

# First submission
intent = TradeIntentRequest(
    intent_id="trade_001",
    symbol="AAPL",
    side=OrderSide.BUY,
    quantity=Decimal("10"),
    order_type=OrderType.MARKET,
    broker_id="my_alpaca"
)
 
response_1 = await client.create_intent(intent)
# Succeeds: 201 Created
 
response_2 = await client.create_intent(intent)
# Fails: 409 Conflict (duplicate intent_id)

⚠️

The intent_id must be unique across all Trade Intents for a given user. Use a UUID or timestamp-based ID to ensure uniqueness.

Trade Intent Lifecycle

Submitted

Trade Intent is submitted to SnipeRoute via API or Python SDK.

Validated

SnipeRoute validates the intent structure and broker connectivity.

Routed

Intent is routed to the specified broker via OAuth-authenticated API call.

Pending

Broker acknowledges the order and begins processing.

Filled / Partially Filled / Rejected

Broker executes the order (or rejects it) and SnipeRoute receives status updates.

Status Values

Status	Description
`pending`	Order submitted to broker, awaiting execution
`filled`	Order fully executed
`partially_filled`	Order partially executed
`canceled`	Order canceled before full execution
`rejected`	Broker rejected the order
`failed`	Routing or validation failed

Order Types

Market Order

Executes immediately at the best available price.

{
  "order_type": "market"
}

Use when: You want immediate execution and don't care about the exact price.

Limit Order

Executes at a specified price or better.

{
  "order_type": "limit",
  "limit_price": 175.00
}

Use when: You want to control the maximum price you pay (buy) or minimum price you receive (sell).

Stop Order

Triggers a market order when the stop price is reached.

{
  "order_type": "stop",
  "stop_price": 170.00
}

Use when: You want to exit a position if the price moves against you (stop-loss).

Stop-Limit Order

Triggers a limit order when the stop price is reached.

{
  "order_type": "stop_limit",
  "stop_price": 170.00,
  "limit_price": 168.00
}

Use when: You want to control both the trigger price and the execution price.

Time in Force

Value	Description
`day`	Order valid until end of trading day (default)
`gtc`	Good-till-canceled (valid until filled or manually canceled)
`ioc`	Immediate-or-cancel (fill immediately or cancel)
`fok`	Fill-or-kill (fill entire order immediately or cancel)

Validation Rules

Limit Orders Must Have limit_price

{
  "order_type": "limit",
  "limit_price": 175.00  // Required
}

Stop Orders Must Have stop_price

{
  "order_type": "stop",
  "stop_price": 170.00  // Required
}

Stop-Limit Orders Must Have Both

{
  "order_type": "stop_limit",
  "stop_price": 170.00,   // Required
  "limit_price": 168.00   // Required
}

Quantity Must Be Positive

{
  "quantity": 10  // Must be > 0
}

Next Steps

Create Your First Intent

Step-by-step guide to submitting your first Trade Intent

API Reference

Complete API documentation for Trade Intents

Authentication Non-Discretionary