Skip to main content

US Stocks Beta

The US Stocks APIs let you trade US-listed stocks and ETFs from your Upstox account. You can place orders in whole or fractional shares, invest a fixed USD amount, track your holdings and wallet, estimate charges, and check US market hours.

These APIs are separate from the Indian trading APIs. All US endpoints live under /v2/us, and the Indian order APIs reject US instruments with UDAPI1251.

Before you begin​

  • Activate US stocks on your Upstox account before you call these APIs. If it isn't active, order, funds, and holdings requests fail with HTTP 403 and error UDAPI1316. To activate it, follow how to start investing in US stocks with Upstox.
  • Get an access token through the standard authentication flow. The same token works for the Indian and US APIs.
  • Download the US instruments file to look up instrument keys and check whether a stock is tradable and fractionable.

Key concepts​

ConceptDetails
Base URLhttps://api.upstox.com/v2/us
Instrument keyUS_EQ|<SYMBOL>, for example US_EQ|AAPL. Take keys from the US instruments file.
CurrencyAll prices, amounts, charges and balances are in USD.
Order typesMARKET and LIMIT. Validity is always DAY.
Order sizingBy quantity (shares, up to 9 decimal places) or by amount (USD, up to 2 decimal places). Fractional quantities and amount orders need a stock with fractionable: true.
Order limitsOrder value must be between $1 and $40,000 (checked when the value is fixed: an amount order, or a limit order at quantity × price). Maximum quantity or amount is 999,999.
Price precisionUp to 2 decimal places at or above $1, and up to 4 below $1. USD values in responses (prices, charges, balances, holdings values) are rounded the same way.
After-market ordersSet automatically. When you place an order, Upstox checks the US market status, and an order placed while the status is anything other than NORMAL_OPEN becomes an after-market order (AMO). There is no is_amo request field.
LeverageNone. Buy orders need the full trade value plus charges.
Rate limitsPlace and Cancel Order: 3 requests per second. Other US APIs: 10 requests per second. See US Stocks rate limits.

Available APIs​

Orders4 APIs

Buy or sell US stocks with market or limit orders. Order by number of shares or by USD amount, check the status of your orders, and cancel any that are still open.

See the US stocks you hold with live value and P&L, and your USD wallet balance and buying power.

Charges2 APIs

See what an order will cost before you place it, including brokerage, GST and US fees. You can also check whether your wallet balance is enough for up to 20 orders at once.

Check US market holidays, session times for any date and the live market status.

On the roadmap

What's coming next

Coming Soon

Real-time US Stocks data

Order updates, market quotes and a live market data feed for US stocks, the same way you use them for the Indian market today.

Order updates
Get US order status changes (placed, filled, cancelled or rejected) as they happen, without polling the order book.
Market data
Fetch LTP market quotes for US stocks over REST.
Live market data feed
Stream live US stock prices tick by tick over WebSocket, instead of polling for quotes.

Typical workflow​

  1. Look up the instrument_key and the fractionable flag in the US instruments file.
  2. Check the Market Status. Orders placed outside the regular session become after-market orders. Use Market Timings to plan around sessions.
  3. Check buying power with Get Funds, and preview costs with Estimate Order Charges.
  4. Place the order, then track it with Get Order Details.
  5. See filled positions in Get Holdings.

US orders can't be modified. To change an open order, cancel it and place a new order.

UDAPI1319 means the US broker did not confirm a place or cancel request in time. The request may still have gone through. Check the order book before you retry, or you may create a duplicate order.

Error handling​

US stocks APIs use the standard error response and their own UDAPI13xx error codes. See US Stocks Error Codes for the full list.