# Ports: several accounts for your bot

> Give each of your bot's strategies its own named simulated account, with its own starting cash and history, and trade or read one by its id.

A **port** is one of your named simulated accounts. Every member has two to start with, and can make up to three more. Each extra port has its own cash, its own history and its own starting balance, so a bot can run two strategies on separate money and you can see which one works.

All tickers, prices, ids and times on this page are made up to show the shape of a call. They aren't real fills and they aren't results.

## What you have

| Port | `kind` | What it is | Counts anywhere public? |
|---|---|---|---|
| **Main** | `main` | Your own simulated wallet, the one you trade by hand. Your ranked port | Yes: ranks, leaderboards, seasons, your profile |
| **Bot** | `bot` | [Your bot's agent account](https://www.skylit.ai/docs/nexus-trades/agent-account), the same as `"account": "agent"` | No |
| **Extra ports** | `extra` | A new simulated account you name, with its own wallet | No |

- **Up to 5 ports in all**, Main and Bot included. Main and Bot are made for you the first time you use ports, from the accounts you already had, so nothing you hold moves.
- **Starting cash** for a new port is one of $10,000, $25,000, $50,000, $100,000 or $250,000.
- **Names** are 1 to 32 characters, with no control characters. Two of your live ports can't share a name, whatever the capitals. You can rename Main and Bot too.
- **Ranked stays on Main.** Bot and every extra port are private practice: they trade on your bot's private book, so nothing public ever counts them.

## The routes

| Method | Path | What it does |
|---|---|---|
| GET | `/api/nexus/v1/trading/ports` | Your ports and the limits |
| POST | `/api/nexus/v1/trading/ports` | Make an extra port: `{"name", "startingCash"}` |
| PATCH | `/api/nexus/v1/trading/ports/{id}` | Rename a port: `{"name"}` |

They use your Skylit API key like every other route here, and count against the same [rate limits](https://www.skylit.ai/docs/nexus-trades/overview#rate-limits): the GET as a read, the POST and the PATCH as writes.

### List your ports

```bash
curl -s "$NEXUS/api/nexus/v1/trading/ports" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

```json
{
  "data": {
    "ports": [
      {
        "id": "0b6f3c1e-2a4d-4e8f-9b1a-7c5d3e2f1a01",
        "name": "Main",
        "kind": "main",
        "startingCash": 100000,
        "isDefault": false,
        "isHandDefault": true,
        "ranked": true,
        "rankedSince": "2026-11-04T15:00:00Z",
        "cooldownUntil": null,
        "resetCount": 0,
        "lastResetAt": null,
        "createdAt": "2026-11-04T15:00:00Z",
        "cashBalance": 101240.5,
        "realizedPnl": 1240.5,
        "openCount": 2,
        "restingOrders": 0,
        "account": null
      },
      {
        "id": "4d2a9e7b-1c3f-4a5e-8d6b-2f1e0a9c8b02",
        "name": "Bot",
        "kind": "bot",
        "startingCash": 100000,
        "isDefault": true,
        "isHandDefault": false,
        "ranked": false,
        "rankedSince": null,
        "cooldownUntil": null,
        "resetCount": 0,
        "lastResetAt": null,
        "createdAt": "2026-11-04T15:00:00Z",
        "cashBalance": 99271,
        "realizedPnl": 124,
        "openCount": 2,
        "restingOrders": 1,
        "account": "agent"
      },
      {
        "id": "9e8d7c6b-5a4f-4e3d-a2c1-0b9a8f7e6d03",
        "name": "Swing",
        "kind": "extra",
        "startingCash": 25000,
        "isDefault": false,
        "isHandDefault": false,
        "ranked": false,
        "rankedSince": null,
        "cooldownUntil": null,
        "resetCount": 0,
        "lastResetAt": null,
        "createdAt": "2026-11-12T14:31:00Z",
        "cashBalance": 24100,
        "realizedPnl": 0,
        "openCount": 1,
        "restingOrders": 0,
        "account": "agent"
      }
    ],
    "limits": {
      "maxPorts": 5,
      "startingCashChoices": [10000, 25000, 50000, 100000, 250000],
      "rankedCooldownDays": 7,
      "rankedStartingCash": 100000,
      "maxNameLength": 32
    }
  }
}
```

- **Money here is in dollars**, not cents: `cashBalance: 24100` is $24,100.00. The [wallet read](#read-a-port) is in cents, like the rest of the API.
- `account` is what to send beside the port on an order or a read: `"agent"` for Bot and every extra port, and `null` for Main, which you send with `account` left out.
- `isDefault` marks Bot, your bot's own account. `isHandDefault` marks Main, where your own hand trades go.
- `openCount` and `restingOrders` are the port's open trades and the orders resting on it right now.
- `resetCount` and `lastResetAt` say how often and when the port was last restarted in Nexus.
- Read `limits` rather than hard-coding them.

### Make a port

```bash
curl -s -X POST "$NEXUS/api/nexus/v1/trading/ports" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Swing","startingCash":25000}'
```

It answers `201` with `{"data": {"port": {...}}}`, the new port in the same shape as the list. Its `id` is what your bot sends from now on.

A create takes no `clientOrderId`. If your bot sends one and never hears back, don't send it blind: a second try answers `409 name_taken` when the first one worked. List your ports and look for the name instead.

### Rename a port

```bash
curl -s -X PATCH "$NEXUS/api/nexus/v1/trading/ports/9e8d7c6b-5a4f-4e3d-a2c1-0b9a8f7e6d03" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Swing v2"}'
```

It answers `200` with the renamed port. The same rename sent twice is the same rename, so it's safe to retry.

### Delete a port

`DELETE /api/nexus/v1/trading/ports/{id}` deletes one of your extra ports, the same delete as in Nexus. It leaves your list and its id stops working: an order or a read that sends it answers `404 port_not_found`. Its trades stay saved, so no list, journal or stats read shows them after this, but a trade read by its own id still answers. You can't undo it. It frees a spot and its name. No body. It counts as a write, so it counts against your 30 writes a minute per key.

Main, Bot and your ranked port always stay, and a port with an open trade or a working order can't be deleted: close and cancel first, nothing is closed for you. A retry after it worked answers `404 port_not_found`, so if you lost the answer, list your ports. It answers `200` with `{"data": {"id": "9e8d7c6b-5a4f-4e3d-a2c1-0b9a8f7e6d03", "deleted": true}}` (the id here is made up). Beta, and only on your own ports.

```bash
curl -s -X DELETE "$NEXUS/api/nexus/v1/trading/ports/$PORT_ID" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

### Only in Nexus

Restarting a port and choosing which port is ranked are yours to do in Nexus, signed in as yourself. A restart puts a wallet back to its start, and that resets history a ranking reads, so no API key can do it. Sent with a key, those routes answer `405 web_only` and nothing is read or changed:

| Method | Path |
|---|---|
| POST | `/api/nexus/v1/trading/ports/{id}/restart` |
| POST | `/api/nexus/v1/trading/ports/{id}/ranked` |

`POST /api/nexus/v1/trading/ports/{id}/archive` answers `405 use_delete` and changes nothing: delete a port with `DELETE` on its own path, above.

## Trade on a port

Add `"port": "<port id>"` to an open. Send the port's `account` beside it, or leave `account` out and the port decides.

```bash
# Options: 2 SPY 600 calls on the Swing port, at market
curl -s -X POST "$NEXUS/api/nexus/v1/trades" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"contract":"SPY 600C 10/16","quantity":2,"account":"agent","port":"9e8d7c6b-5a4f-4e3d-a2c1-0b9a8f7e6d03","clientOrderId":"swing-0001"}'
```

- **Main** is your own wallet, the same as an order with no `account`. Send it with `account` left out: `"account": "agent"` beside Main answers `400 bad_request`.
- **Bot** is the same as `"account": "agent"`, futures included.
- **An extra port** pays from and fills on its own wallet. `account` must be `"agent"` or left out.
- **Left out**, `port` changes nothing: `account` alone decides, exactly as before ports.
- A trade on an extra port carries `portId` in every trade read. Exits and adds go by the trade's id, as always, and stay on that trade's port.

### What an extra port takes

| On an extra port | Answer |
|---|---|
| Market opens, exits and adds of options and stocks | Yes |
| Test orders of those | Yes |
| Options limit orders, and stock limit and stop orders | Yes |
| A stop-loss or take-profit on an options trade, or a stop and target on an entry | Not yet: `422 port_unsupported` |
| Futures | Not yet: `422 port_unsupported`. Futures go to your practice account or your Bot port |

A resting order on an extra port holds back that port's own buying power, fills on its wallet and refunds to it when you cancel. You reach it under `wallets/agent` with `?port=`:

```bash
curl -s "$NEXUS/api/nexus/v1/trading/wallets/agent/orders/working?port=9e8d7c6b-5a4f-4e3d-a2c1-0b9a8f7e6d03" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

Every order route under `wallets/{book}/orders` takes `?port=`. Main's orders are under `wallets/main`, and Bot's and every extra port's under `wallets/agent`. The wrong wallet answers `400 bad_request` and names the right one. A resting order on an extra port carries `portId`.

## Read a port

| What | Call |
|---|---|
| Its trades | `GET /api/nexus/v1/trades?account=agent&port=<id>` |
| Its wallet | `GET /api/nexus/v1/trading/wallets/agent?port=<id>` |
| What rests on it | `GET /api/nexus/v1/trading/wallets/agent/orders/working?port=<id>` |
| Its journal and Edge | [Journal and Edge](https://www.skylit.ai/docs/nexus-trades/journal-api) with `?port=<id>` |

The wallet answers in the [usual shape](https://www.skylit.ai/docs/nexus-trades/agent-account#check-the-wallet), in cents, with `port` set to the port you asked for. Main's wallet is under `wallets/main`. Asking for a port under the other wallet answers `400 bad_request`.

## Errors

| Status | `code` | What it means | What your bot should do |
|---|---|---|---|
| 400 | `bad_request` | `account` doesn't agree with the port, or the port's wallet is under the other `{book}`. The message says which | Send the port's own `account`, or leave `account` out |
| 400 | `bad_name` | The name is empty, longer than 32 characters, or has a control character | Fix the name |
| 400 | `bad_starting_cash` | `startingCash` is missing or not one of the choices | Pick one from `limits.startingCashChoices` |
| 403 | `feature_disabled` | Ports are switched off on the server for now | Leave `port` out. Nothing else changes |
| 404 | `port_not_found` | No live port with that id on your account. Someone else's port answers the same | List your ports for the right id |
| 405 | `web_only` | Restart or ranked, sent with a key | Do it in Nexus |
| 405 | `use_delete` | `POST .../archive` | Send `DELETE /api/nexus/v1/trading/ports/{id}` |
| 409 | `port_limit` | You already have 5 ports | Delete one first |
| 409 | `open_positions` | A delete on a port that still has an open trade or a working order | Close and cancel first, then delete |
| 409 | `cannot_delete_default` | A delete on Main or Bot | They always stay |
| 409 | `cannot_delete_ranked` | A delete on your ranked port | Make another port ranked in Nexus first |
| 409 | `name_taken` | You already have a live port with that name | Pick another name, or list your ports: a retried create lands here |
| 422 | `port_unsupported` | That port doesn't take this kind of order yet. Nothing was placed | Send a market order, or use Main or Bot |
| 503 | `unavailable` | Your ports couldn't be read right now | Retry in a moment |
