> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta trading

> Connect a persona's brokerage account, read it, and place orders.

A [persona](https://vetta.sh/docs/cli/identity.md) can connect its own brokerage account — `paper` or `live` — and trade through it from the terminal. Every command takes `--identity` (an `idn_` id or the persona's name). `--env paper|live` is needed only when both are connected. Naive Managed Agents is not a broker or an investment adviser, holds no customer money, and nothing it says about a symbol is investment advice; the terminal places exactly the order you type. See [Trading](https://vetta.sh/docs/identity/trading.md) for the model. See the [SDK reference](https://vetta.sh/docs/sdk/trading.md) for the wire shapes.

Prices and notionals are typed in dollars (`--limit-price-usd 180.25`) and converted once to the integer micro-USD the API speaks; quantities stay decimals (`--qty 0.5`). The writes — `connect`, `disconnect`, `buy`, `sell`, `cancel`, `close` — need a key with the `billing:write` scope, and on a `live` account a live `sk_live_` key.

## Commands

| Command | Description |
| - | - |
| `vetta trading connect` | Print the consent text and the link that connects a brokerage account. |
| `vetta trading connections` | Show both envs' connection status. |
| `vetta trading disconnect` | Disconnect one env and delete its token. |
| `vetta trading account` | Cash, buying power and equity. |
| `vetta trading positions` | Open positions. |
| `vetta trading orders` | List orders. |
| `vetta trading order` | Read one order. |
| `vetta trading quote` | Latest bid and ask for one or more symbols. |
| `vetta trading buy` | Place a buy order. |
| `vetta trading sell` | Place a sell order. |
| `vetta trading cancel` | Cancel an open order. |
| `vetta trading close` | Close a position, in full or in part. |

## connect / connections / disconnect

```bash theme={"system"}
vetta trading connect --identity ava --env paper
vetta trading connections --identity ava
vetta trading disconnect --identity ava --env live
```

`connect` prints the brokerage's consent text first and the link after it: read the text, then open the link in a browser and approve. The link works once and expires after 15 minutes. `connections` then shows the env as `active`; `expired` means the brokerage revoked access and you need to connect again. `--env` is required on `connect` and `disconnect`.

## account / positions / orders / order / quote

```bash theme={"system"}
vetta trading account --identity ava
vetta trading positions --identity ava --env live
vetta trading orders --identity ava --status all --limit 20
vetta trading order --identity ava --order 61e69015-8549-4bfd-b9c3-01e75843f47d
vetta trading quote --identity ava --symbols AAPL,MSFT
vetta trading quote --identity ava --symbols BTC/USD --asset-class crypto
```

| Flag | Description |
| - | - |
| `--env` | `paper` or `live`; needed only when both are connected. |
| `--status` | `orders`: `open` (default), `closed` or `all`. |
| `--limit` | `orders`: 1–500 (default 50). |
| `--order` | The order id (`order`, `cancel`). |
| `--symbols` | `quote`: comma-separated, up to 100. Crypto symbols are slashed (`BTC/USD`). |
| `--asset-class` | `quote`: `us_equity` (default) or `crypto`. |

## buy / sell

```bash theme={"system"}
vetta trading buy --identity ava --env paper --symbol AAPL --qty 1 --type limit --limit-price-usd 180.25 --time-in-force day
vetta trading sell --identity ava --env paper --symbol BTC/USD --notional-usd 25 --type market --time-in-force gtc
```

| Flag | Description |
| - | - |
| `--symbol` | What to trade (required). |
| `--type` | `market`, `limit`, `stop` or `stop_limit` (required — there is no default). |
| `--time-in-force` | `day`, `gtc`, `ioc`, `fok`, `opg` or `cls` (required). |
| `--qty` | Quantity as a decimal. Give exactly one of `--qty` and `--notional-usd`. |
| `--notional-usd` | Dollar amount to trade instead of a quantity. |
| `--limit-price-usd` | Required on `limit` and `stop_limit`, refused on the others. |
| `--stop-price-usd` | Required on `stop` and `stop_limit`, refused on the others. |
| `--extended-hours` | Allow the order to fill outside regular hours. |
| `--client-order-id` | Your own idempotency key (up to 128 characters). Without it each run sends a new key, so running `buy` again places a second order; pass the same `--client-order-id` to make a retry safe. |

The brokerage's own rules — a minimum notional, which time-in-force a coin accepts — come back as `validation_failed` or `forbidden` with its reason.

## cancel / close

```bash theme={"system"}
vetta trading cancel --identity ava --order 61e69015-8549-4bfd-b9c3-01e75843f47d
vetta trading close --identity ava --symbol AAPL --percentage 50
vetta trading close --identity ava --symbol BTCUSD
```

`close` takes at most one of `--qty` and `--percentage` (greater than 0, at most 100); neither closes the whole position. A crypto position's symbol is written without a slash (`BTCUSD`), as `positions` prints it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.