# Nexus Trades API field guide

> Let your own bot or script open, trim, close and read paper trades in your Nexus accounts, under the same prices and rules as a trade you place by hand.

> **Note:** Educational material, not financial advice. Nothing here is a recommendation to buy or sell any security. Options and futures involve significant risk and are not suitable for every investor. Paper results don't guarantee future results.

> **Note:** **Beta.** The Nexus Trades API works with your Skylit API key and is still in active development. Routes, limits and fields can change. Check what your key can do with `GET /api/nexus/v1/trading/capabilities`.

## Why it matters
If you run a bot, you probably can't tell how it really trades. It fires orders somewhere, and the record lives in a log file nobody reads. Nexus already scores and charts every paper trade you take by hand. The Trades API lets your bot post its trades there too, so you see its P/L, its open positions and its account rules in the same place as your own.

Three things make it worth using:

- **Same prices as the ticket.** The server fills every order from the live market when it arrives. Your bot can't pick a better fill than you'd get clicking it in Nexus.
- **Same rules as the ticket.** An order into an evaluation or a funded account runs under that account's daily loss limit, max loss and contract cap, exactly as if you'd placed it yourself.
- **Safe to retry.** Send a `clientOrderId` with an order and a dropped connection can't fill it twice.

> **Info:** **In plain English.** Nexus is your paper trading account. This is a way for your own code to trade it for you. It's paper only: nothing reaches a broker or a real market.

## Where to find it
- **Your key:** the [Developer page](https://app.skylit.ai/developer). It's the same Skylit API key you'd use for market data.
- **The base URL:** `https://app.skylit.ai`, with every route under `/api/nexus/v1/`.
- **The getting started guide:** [Nexus Trades API](https://www.skylit.ai/docs/nexus-trades/overview): auth, limits, retries, time and price rules, a Python and a JavaScript bot, and every error code.
- **Rehearsing:** [Test orders](https://www.skylit.ai/docs/nexus-trades/test-orders).
- **Every route:** the [API Reference](https://www.skylit.ai/docs/api-reference/account-and-capabilities/what-this-key-can-trade-right-now) tab of the Nexus section here, or in the app under **Developer > API reference > [Nexus Trades](https://app.skylit.ai/developer/api?product=nexus-trades)**.
- **Your trades:** in Nexus itself. Options and stock trades from the API are regular Nexus paper trades, so they sit in **Trades** with the rest of yours. Futures orders land on the account they went to.

## Read it in 30 seconds
| | |
| --- | --- |
| **What it does** | Opens, trims, closes and reads your Nexus paper trades |
| **Where orders go** | Options and stocks: your paper wallet. Futures: your practice account, or an evaluation or funded account you name |
| **Sign-in** | Your Skylit API key as a bearer token |
| **Order types** | Options and stocks: market. Futures: market, limit and stop, with an optional stop loss and take profit |
| **Fills** | Priced by the server from the live market. You never send a time |
| **Limits** | 30 writes and 120 reads a minute per key. 50 open options and stock positions from the API |
| **Credits** | None. Trades calls don't spend API credits |
| **Rehearsal** | `"test": true` checks and prices an order, then doesn't place it |
| **Broker** | Never. Paper trades inside Nexus only |

## How to use it
### Start with capabilities
**Why:** your bot shouldn't guess. One call says which asset classes, order types, futures contracts and accounts this key can trade right now, whether the futures market is open, and your rate limits.

**Where:** `GET /api/nexus/v1/trading/capabilities`. Run it when your bot starts, and again before it trades futures.

Read `futures.accounts` for your account ids. Each one says if the API can trade it (`tradable`) and what it may do there (`allowed`).

### Options and stocks
**Why:** mirror a trade your bot made somewhere else into Nexus, so it's scored with the rest of your trading.

1. Open with `POST /api/nexus/v1/trades`. Send the contract as four fields (`ticker`, `direction`, `strike`, `expiration`) or as one string like `"SPY 600C 10/16"`. Stocks take `"assetClass": "stocks"` and a `side`.
2. Keep the `id` it returns.
3. Trim with `POST /api/nexus/v1/trades/{id}/exits` and a `quantity`, or close with `"closeAll": true`.

Want Nexus to record the price your bot actually got? Send `price`. It's taken only inside a small window around the live quote. Outside it, the order is refused, or fills at market if you sent `"ifOutside": "market"`.

Options are bought to open only, and it's one position per contract. A second open on a contract you hold answers `409 duplicate_position`.

### Futures
**Why:** run a futures bot on paper money with the same contracts, hours and fills as the Nexus futures ticket.

1. Open with `POST /api/nexus/v1/trades`, `"assetClass": "futures"`, a `ticker` (`NQ` trades the front month) and a `side`.
2. Close with `POST /api/nexus/v1/trading/accounts/{account}/close`: a `ticker` for one position, `"closeAll": true` to flatten.
3. Read the account with `GET /api/nexus/v1/trading/accounts/{account}`: balance, day P/L, positions, resting orders and, on evaluation and funded accounts, the rules and how far you are from each one.

Futures net per account and contract. There's no trade id to exit, so use the close route. It closes exactly what you hold and can't flip you. Money in futures answers is in cents: `balanceCents: 5000000` is \$50,000.00.

### Resting orders and brackets
**Why:** let a futures order wait for your price, and protect it with a stop and a target, the same way you would on the ticket.

- Send `"orderType": "limit"` with `limitPrice`, or `"stop"` with `stopPrice`.
- Add `stopLoss` and `takeProfit` to any futures order, a market order included. `"trailingStop": true` makes the stop follow the price.
- See what's resting with `.../orders/working`. Move a price with `.../orders/{orderId}/modify`. Cancel one with `.../cancel`, or everything with `.../orders/cancel`.

A price is where your order rests, never where it fills. It fills when the market trades through it.

> **Warning:** **Cancelling everything doesn't flatten you.** `.../orders/cancel` also cancels the stop and target behind an open position, and leaves the position open with nothing behind it. To get flat, use the close route.

### Evaluation and funded accounts
**Why:** test whether your bot can respect an evaluation's rules before you trust it with one.

- Name the account: `"account": "evaluation"`, `"funded"` or its id. An order never lands there unless you name it.
- The account's rules apply as they do in Nexus: the daily loss limit, the max loss, the contract cap, flat by the close and your own risk settings.
- A bot that breaks a rule locks or fails the account the same way you would by hand.
- `"reduceOnly": true` on a market order makes sure it can only shrink a position you hold. Use it, or the close route, whenever your bot is taking something off.
- Challenge entries can be read but not traded through the API.

### Test orders
**Why:** find out whether an order would go through, and at what price, before your bot sends it for real.

Add `"test": true`. The order gets every real check against your real account and the live market, then it's kept in a 10-row test log instead of being placed. A bot left in test mode can't sell a real position. See [Test orders](https://www.skylit.ai/docs/nexus-trades/test-orders) for the details and the limits.

### Retries
**Why:** networks drop answers. Without an id, a resend is a second order.

Send a `clientOrderId` you make up with every order. Send the same id again and you get the first order back, with nothing new placed, for 24 hours. On futures there's no duplicate check, so this is the only thing that stops a resend from doubling your position.

## Use it with other Skylit tools
- **Nexus.** Every options and stock trade your bot opens is a regular Nexus paper trade. It counts in your stats and feed like one you placed by hand, and the API marks it `"source": "api"`.
- **The market data API.** Your bot can read positioning, flow and volatility from the [market data API](https://www.skylit.ai/docs/api-reference/introduction) with the same key, then trade the idea on paper here. The data API stays read-only, and neither one serves futures market data.
- **The MCP server.** The [MCP server](https://www.skylit.ai/docs/mcp/overview) reads market data for your AI assistant. It can't place trades yet. For now, trade from your own code with this API.

## Good to know
- **Paper only.** Nothing here reaches a broker, even one you've connected to Nexus.
- **Your trades only.** A key sees and trades its owner's trades and accounts. Someone else's id answers "not found".
- **Market hours apply.** Outside them an order answers `422 market_closed`. It isn't queued for the open.
- **A missing number means "not measured".** When a contract you hold has no live price, P/L fields are left out rather than set to zero. Check before you do math.
- **Revoking is fast.** A key you revoke stops working here within about a minute. That's the quickest way to stop a bot.
- **Read your limits, don't hard-code them.** Each answer carries `X-RateLimit-Remaining`, and `capabilities` reports the limits that apply to your key.
- **Not there yet:** limit or stop orders for options and stocks, stop-limit orders, changing a resting order's size, adding to an open options or stock position, selling options to open, a push feed of fills, and creating or resetting accounts. Do those in Nexus.
- **Educational.** Nexus is a beta for reviewing your own trading. Nothing here is advice.