# 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
PermissionDescription
listTrader is allowed to know about the account but not its balances or positions
reduce_or_closeTrader can send orders only to reduce or close (risk manager)
set_limitsTrader allowed to set or change risk limits on the account
tradeTrader allowed to send orders
viewRead-only view of account, including balances and positions
## 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
FieldDescription
accountAccount ID
timestampSnapshot timestamp
equityTotal account equity or net liquidation value
cash_excessWithdrawable cash
purchasing_powerTotal purchasing power of the account
unrealized_pnlUnrealized P&L
realized_pnlRealized P&L
yesterday_equityYesterday account equity or net liquidation value; not provided on all venues
total_marginMargin usage including open orders and positions
position_marginMargin usage including only positions
balancesMap of products/assets to their quantities
positionsSee "Account Positions" 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.architect.co/sdk-reference/portfolio-management.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.