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
403and errorUDAPI1316. 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
| Concept | Details |
|---|---|
| Base URL | https://api.upstox.com/v2/us |
| Instrument key | US_EQ|<SYMBOL>, for example US_EQ|AAPL. Take keys from the US instruments file. |
| Currency | All prices, amounts, charges and balances are in USD. |
| Order types | MARKET and LIMIT. Validity is always DAY. |
| Order sizing | By 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 limits | Order 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 precision | Up 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 orders | Set 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. |
| Leverage | None. Buy orders need the full trade value plus charges. |
| Rate limits | Place and Cancel Order: 3 requests per second. Other US APIs: 10 requests per second. See US Stocks rate limits. |
Available 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.
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.
What's coming next
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.
Typical workflow
- Look up the
instrument_keyand thefractionableflag in the US instruments file. - Check the Market Status. Orders placed outside the regular session become after-market orders. Use Market Timings to plan around sessions.
- Check buying power with Get Funds, and preview costs with Estimate Order Charges.
- Place the order, then track it with Get Order Details.
- 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.