Your First Trade Intent

Step-by-step guide to creating and submitting Trade Intents

Prerequisites

Before you begin, make sure you have:

SnipeRoute account and API key
Python SDK installed (pip install sniperoute)
Connected broker account (or use mock broker for testing)

Step 1: Import Dependencies

import asyncio
from sniperoute import SnipeRouteClient
from sniperoute.models import (
    TradeIntentRequest,
    OrderSide,
    OrderType,
    TimeInForce
)
from decimal import Decimal

Step 2: Initialize Client

import os
from sniperoute import SnipeRouteClient
 
# Automatically uses SNIPEROUTE_API_KEY and SNIPEROUTE_API_URL
client = SnipeRouteClient()

Step 3: Create a Market Order

Let's start with a simple market buy order:

async def create_market_order():
    # Create Trade Intent
    intent = TradeIntentRequest(
        intent_id="my_first_trade",
        symbol="AAPL",
        side=OrderSide.BUY,
        quantity=Decimal("10"),
        order_type=OrderType.MARKET,
        broker_id="mock"  # Use "mock" for testing
    )
 
    # Submit to SnipeRoute
    response = await client.create_intent(intent)
 
    print(f"Intent created!")
    print(f"   Intent ID: {response.intent_id}")
    print(f"   Status: {response.status}")
    print(f"   Internal ID: {response.id}")
 
    return response
 
# Run
asyncio.run(create_market_order())

Expected Output

Intent created!
   Intent ID: my_first_trade
   Status: pending
   Internal ID: 550e8400-e29b-41d4-a716-446655440000

Step 4: Create a Limit Order

Now let's create a limit order with price control:

async def create_limit_order():
    intent = TradeIntentRequest(
        intent_id="limit_order_001",
        symbol="TSLA",
        side=OrderSide.BUY,
        quantity=Decimal("5"),
        order_type=OrderType.LIMIT,
        limit_price=Decimal("250.00"),  # Required for limit orders
        time_in_force=TimeInForce.GTC,  # Good-till-canceled
        broker_id="mock"
    )
 
    response = await client.create_intent(intent)
 
    print(f"Limit order created!")
    print(f"   Symbol: {response.symbol}")
    print(f"   Side: {response.side}")
    print(f"   Quantity: {response.quantity}")
    print(f"   Limit Price: {response.limit_price}")
 
    return response
 
asyncio.run(create_limit_order())

Expected Output

Limit order created!
   Symbol: TSLA
   Side: buy
   Quantity: 5
   Limit Price: 250.00

Step 5: Check Intent Status

After submitting an intent, you can check its status:

async def check_status():
    # Get intent by your external ID
    intent = await client.get_intent_by_external_id("my_first_trade")
 
    print(f"Status: {intent.status}")
    print(f"Symbol: {intent.symbol}")
    print(f"Orders: {len(intent.orders)}")
 
    # Check fills
    for order in intent.orders:
        print(f"\nOrder {order.broker_order_id}:")
        print(f"  Status: {order.status}")
 
        for fill in order.fills:
            print(f"  Fill: {fill.quantity} @ ${fill.price}")
 
asyncio.run(check_status())

Expected Output

Status: filled
Symbol: AAPL
Orders: 1

Order mock_order_123:
  Status: filled
  Fill: 10 @ $175.50

Step 6: Sell Order Example

Let's create a sell order:

async def create_sell_order():
    intent = TradeIntentRequest(
        intent_id="sell_order_001",
        symbol="AAPL",
        side=OrderSide.SELL,  # Note: SELL instead of BUY
        quantity=Decimal("10"),
        order_type=OrderType.LIMIT,
        limit_price=Decimal("180.00"),
        time_in_force=TimeInForce.DAY,
        broker_id="mock"
    )
 
    response = await client.create_intent(intent)
    print(f"Sell order created: {response.intent_id}")
 
    return response
 
asyncio.run(create_sell_order())

Complete Example

Here's a complete script with error handling:

import asyncio
from sniperoute import SnipeRouteClient
from sniperoute.models import TradeIntentRequest, OrderSide, OrderType
from sniperoute.exceptions import SnipeRouteAPIError
from decimal import Decimal
 
async def main():
    try:
        # Initialize client
        client = SnipeRouteClient()
 
        # Create Trade Intent
        intent = TradeIntentRequest(
            intent_id="complete_example_001",
            symbol="NVDA",
            side=OrderSide.BUY,
            quantity=Decimal("20"),
            order_type=OrderType.LIMIT,
            limit_price=Decimal("500.00"),
            broker_id="mock"
        )
 
        # Submit intent
        print("Submitting Trade Intent...")
        response = await client.create_intent(intent)
 
        print(f"Intent submitted successfully!")
        print(f"   Intent ID: {response.intent_id}")
        print(f"   Status: {response.status}")
 
        # Check status
        print("\nChecking status...")
        status = await client.get_intent_by_external_id("complete_example_001")
 
        print(f"Current status: {status.status}")
 
        if status.status == "filled":
            print("Order fully filled!")
            for order in status.orders:
                for fill in order.fills:
                    print(f"   {fill.quantity} shares @ ${fill.price}")
        elif status.status == "pending":
            print("⏳ Order pending execution...")
        elif status.status == "rejected":
            print("Order rejected by broker")
 
    except SnipeRouteAPIError as e:
        print(f"API Error: {e.message}")
        print(f"   Status Code: {e.status_code}")
    except Exception as e:
        print(f"Unexpected error: {e}")
 
if __name__ == "__main__":
    asyncio.run(main())

Common Order Types

Market Order (Immediate Execution)

TradeIntentRequest(
    intent_id="market_001",
    symbol="AAPL",
    side=OrderSide.BUY,
    quantity=Decimal("10"),
    order_type=OrderType.MARKET,
    broker_id="my_broker"
)

Limit Order (Price Control)

TradeIntentRequest(
    intent_id="limit_001",
    symbol="AAPL",
    side=OrderSide.BUY,
    quantity=Decimal("10"),
    order_type=OrderType.LIMIT,
    limit_price=Decimal("175.00"),
    broker_id="my_broker"
)

Stop-Loss Order

TradeIntentRequest(
    intent_id="stop_001",
    symbol="AAPL",
    side=OrderSide.SELL,
    quantity=Decimal("10"),
    order_type=OrderType.STOP,
    stop_price=Decimal("170.00"),
    broker_id="my_broker"
)

Stop-Limit Order

TradeIntentRequest(
    intent_id="stop_limit_001",
    symbol="AAPL",
    side=OrderSide.SELL,
    quantity=Decimal("10"),
    order_type=OrderType.STOP_LIMIT,
    stop_price=Decimal("170.00"),
    limit_price=Decimal("168.00"),
    broker_id="my_broker"
)

Time in Force Options

from sniperoute.models import TimeInForce
 
# Day order (expires at market close)
time_in_force=TimeInForce.DAY
 
# Good-till-canceled (active until filled or manually canceled)
time_in_force=TimeInForce.GTC
 
# Immediate-or-cancel (fill immediately or cancel)
time_in_force=TimeInForce.IOC
 
# Fill-or-kill (fill entire order immediately or cancel)
time_in_force=TimeInForce.FOK

Common Errors

409 Conflict - Duplicate intent_id

Problem: You're using an intent_id that already exists.

Solution: Use a unique identifier for each Trade Intent (e.g., UUID or timestamp).

import uuid
 
intent_id = f"trade_{uuid.uuid4()}"

400 Bad Request - Missing limit_price

Problem: Limit orders require a limit_price.

Solution: Add limit_price to your Trade Intent.

intent = TradeIntentRequest(
    # ...
    order_type=OrderType.LIMIT,
    limit_price=Decimal("175.00")  # Required!
)

401 Unauthorized - Invalid API key

Problem: Your API key is missing or invalid.

Solution: Check your API key in the dashboard and ensure it's properly set.

client = SnipeRouteClient(
    api_key="sk_live_your_valid_key_here"
)

404 Not Found - Broker not connected

Problem: The broker_id doesn't exist or isn't connected.

Solution: Go to the dashboard and connect your broker account via OAuth.

Next Steps

Connect Real Broker

Link your Alpaca, IBKR, or Schwab account

Webhook Setup

Receive real-time status updates

Error Handling

Handle errors and retries

API Reference

Complete API documentation

Non-Custodial Connecting Brokers