# Portfolio management

* [Portfolio management](#portfolio-management)
  * [List accounts](#list-accounts)
    * [Account permissions](#account-permissions)
  * [Get account summary](#get-account-summary)
    * [Account summary fields](#account-summary-fields)
  * [Get account history](#get-account-history)
  * [Paper Trading Accounts](#paper-trading-accounts)
    * [Enable paper trading (GraphQL)](#enable-paper-trading-graphql)
    * [Open paper account](#open-paper-account)
    * [Reset paper account](#reset-paper-account)

## List accounts

List all accounts available to the user. This includes FCM accounts, which must be specified when sending orders.

{% tabs %}
{% tab title="Python" %}

```python
res = await client.list_accounts()

for item in res:
    print(item.account.name)
```

{% endtab %}

{% tab title="Example JSON response" %}

```json5
[
  {
    account: {
      id: "00000000-0000-0000-0000-000000000000",
      name: "STONEX:000000/JDoe",
    },
    permissions: {
      list: true,
      reduce_or_close: true,
      set_limits: true,
      trade: true,
      view: true,
    },
    trader: "00000000-0000-0000-0000-000000000000",
  },
  {
    account: {
      id: "00000000-0000-0000-0000-000000000001",
      name: "STONEX:000001/JDoe",
    },
    permissions: {
      list: true,
      reduce_or_close: true,
      set_limits: true,
      trade: true,
      view: true,
    },
    trader: "00000000-0000-0000-0000-000000000000",
  },
]
```

{% endtab %}
{% endtabs %}

### Account permissions

<table><thead><tr><th width="193.8046875">Permission</th><th>Description</th></tr></thead><tbody><tr><td>list</td><td>Trader is allowed to know about the account but not its balances or positions</td></tr><tr><td>reduce_or_close</td><td>Trader can send orders only to reduce or close (risk manager)</td></tr><tr><td>set_limits</td><td>Trader allowed to set or change risk limits on the account</td></tr><tr><td>trade</td><td>Trader allowed to send orders</td></tr><tr><td>view</td><td>Read-only view of account, including balances and positions</td></tr></tbody></table>

## Get account summary

Get an account summary for a specified account.

{% tabs %}
{% tab title="Python" %}

```python
res = await client.get_account_summary("STONEX:000000/JDoe")
print(res)

# get multiple account summaries
res = await client.get_account_summaries([
    "STONEX:000000/JDoe",
    "STONEX:000001/JDoe"
])
print(res)
```

{% endtab %}

{% tab title="Example JSON response" %}

```json5
{
  account: "00000000-0000-0000-0000-000000000000",
  balances: {
    USD: "5754.59",
  },
  positions: {
    "MGC 20250626 CME Future/USD": [
      {
        quantity: "1",
        cost_basis: "3279.2",
      },
    ],
  },
  timestamp: "2025-05-15T22:32:21.222906Z",
  cash_excess: "0",
  position_margin: "1650",
  purchasing_power: "5447.59",
  realized_pnl: "0",
  total_margin: "1650",
  unrealized_pnl: "0",
}
```

{% endtab %}
{% endtabs %}

### Account summary fields

<table><thead><tr><th width="221.86328125">Field</th><th>Description</th></tr></thead><tbody><tr><td>account</td><td>Account ID</td></tr><tr><td>timestamp</td><td>Snapshot timestamp</td></tr><tr><td>equity</td><td>Total account equity or net liquidation value</td></tr><tr><td>cash_excess</td><td>Withdrawable cash</td></tr><tr><td>purchasing_power</td><td>Total purchasing power of the account</td></tr><tr><td>unrealized_pnl</td><td>Unrealized P&#x26;L</td></tr><tr><td>realized_pnl</td><td>Realized P&#x26;L</td></tr><tr><td>yesterday_equity</td><td>Yesterday account equity or net liquidation value; not provided on all venues</td></tr><tr><td>total_margin</td><td>Margin usage including open orders and positions</td></tr><tr><td>position_margin</td><td>Margin usage including only positions</td></tr><tr><td>balances</td><td>Map of products/assets to their quantities</td></tr><tr><td>positions</td><td>See "Account Positions" table</td></tr></tbody></table>

## Get position summary

Get an aggregated summary of positions and a snapshot of unrealized PnL and notional value for a specified account(s).

{% tabs %}
{% tab title="Python" %}

```python
# defaults to all accounts
res = await client.get_positions_summary()
print(res)
```

{% endtab %}

{% tab title="Example JSON response" %}

```json5
{
  direction: "BUY",
  quantity: "10",
  symbol: "NQ 20251219 CME Future/USD",
  avg_cost_basis: "25730",
  current_price: "25706.75",
  notional_usd: "5141350",
  unrealized_pnl: "-4650",
}
```

{% endtab %}
{% endtabs %}

## Get account history

Get historical snapshots of account summaries for the specified account.

{% tabs %}
{% tab title="Python" %}

```python
from datetime import datetime

res = await client.get_account_history(
    account="STONEX:000000/JDoe",
    from_inclusive=datetime(2025, 1, 1),
    to_exclusive=datetime(2025, 1, 2)
)
print(res)
```

{% endtab %}
{% endtabs %}

## Paper Trading Accounts

Paper trading accounts allow users to test strategies and practice trading without real money. Each user automatically has access to a default paper account with the format `PAPER:{email}`. Users can create up to 2 additional paper accounts.

### Enable paper trading (GraphQL)

Enable paper trading for the authenticated user through the GraphQL API. This creates the default paper account if it doesn't exist.

{% tabs %}
{% tab title="GraphQL" %}

```graphql
mutation {
  user {
    enablePaperTrading
  }
}
```

{% endtab %}

{% tab title="Example Response" %}

```json
{
  "data": {
    "user": {
      "enablePaperTrading": true
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Open paper account

Create a new paper trading account for the authenticated user.

**Request Parameters:**

* `account_name` (optional): Custom name for the paper account
  * If not specified, creates/accesses the default account `PAPER:{email}`
  * When specified, creates account as `PAPER:{email}:{account_name}`
* `usd_balance_cents` (optional): Initial balance in USD cents
  * If not specified, uses default balance ($100,000)

{% tabs %}
{% tab title="Python" %}

```python
# Create default paper account
res = await client.open_paper_account()
print(f"Account: {res.account.name}")
print(f"Account ID: {res.account.id}")

# Create named account with custom balance
res = await client.open_paper_account(
    account_name="my_strategy_test",
    usd_balance_cents=500000  # $5,000.00
)
print(f"Account: {res.account.name}")
```

{% endtab %}

{% tab title="Example Response" %}

```json
{
  "account": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "PAPER:user@example.com:my_strategy_test"
  }
}
```

{% endtab %}
{% endtabs %}

**Note:** Users can have 1 default account plus up to 2 additional named accounts. Contact Architect for access to additional accounts.

### Reset paper account

Reset the cash balance in a paper account.

**Request Parameters:**

* `account`: Account identifier (UUID or name)
  * Accepts: `PAPER:{email}`, `PAPER:{email}:{name}`, or account UUID
* `usd_balance_cents` (optional): Balance to reset to in USD cents
  * If not specified, resets to default balance

{% tabs %}
{% tab title="Python" %}

```python
# Reset account to default balance
res = await client.reset_paper_account("PAPER:user@example.com")

# Reset account with a specific balance
res = await client.reset_paper_account(
    account="PAPER:user@example.com:my_strategy_test",
    usd_balance_cents=100000  # $1,000.00
)

# Reset using account UUID
res = await client.reset_paper_account(
    account="00000000-0000-0000-0000-000000000000",
    usd_balance_cents=500000  # $5,000.00
)
```

{% endtab %}

{% tab title="Example Response" %}

```json
{
  // Empty response indicates success
}
```

{% endtab %}
{% endtabs %}

### Error Handling

Common error scenarios and solutions:

**Account Limit Exceeded**

* Error when trying to create more than three paper accounts
* Solution: Contact Architect for increased limits, support\[at]architect.co

**Account Not Found**

* Specified account doesn't exist for reset operations
* Verify account name/ID is correct
* Ensure account was created before attempting operations