Portfolio

The Portfolio API manages trading portfolios within the Paper platform. Use this API to create portfolios, manage positions, track day trades, configure margin settings, and monitor portfolio performance.

Overview

Portfolios represent trading accounts that track cash balances, equity positions, margin requirements, and trading activity. Each account can have multiple portfolios with different configurations (cash vs margin, individual vs IRA, etc.).

API Endpoints Overview

Endpoint	Method	Description
`/v1/accounts/portfolios`	POST	Create a new portfolio
`/v1/accounts/portfolios/:portfolioId`	GET	Get portfolio details
`/v1/accounts/:accountId/portfolios`	GET	Get all portfolios for an account
`/v1/accounts/portfolios/:portfolioId/equities`	GET	Get equity positions
`/v1/accounts/portfolios/:portfolioId/options`	GET	Get option positions
`/v1/accounts/portfolios/:portfolioId/day-trades`	GET	Get day trade activity
`/v1/accounts/portfolios/:portfolioId/margin-eligibility`	GET	Check portfolio margin eligibility
`/v1/accounts/portfolios/:portfolioId/margin-upgrade`	PUT	Upgrade portfolio margin type
`/v1/accounts/portfolios/:portfolioId/broker`	PUT	Switch portfolio broker configuration
`/v1/accounts/portfolios/:portfolioId/reset`	POST	Reset a portfolio

Available Brokers

When creating or updating a portfolio, you must specify a broker configuration. Each broker has different commission rates and trading features.

Broker ID	Name	Commission (Equity/Option)
`default`	Default Broker	$0.00 / $0.50
`ally-invest`	Ally Invest	$0.00 / $0.50
`alpaca`	Alpaca	$0.00 / $0.00
`cobra-trading`	Cobra Trading	$0.003 per share / $0.30
`etrade`	E*TRADE	$0.00 / $0.50
`fidelity`	Fidelity	$0.00 / $0.65
`firstrade`	Firstrade	$0.00 / $0.00
`interactive-brokers`	Interactive Brokers	$0.005 per share / $0.50
`jpmorgan`	J.P. Morgan Self-Directed Investing	$0.00 / $0.65
`lightspeed`	Lightspeed	$0.0045 per share / $0.50
`merrill-edge`	Merrill Edge	$0.00 / $0.65
`moomoo`	moomoo	$0.00 / $0.50
`public`	Public.com	$0.00 / $0.00
`robinhood`	Robinhood	$0.00 / $0.00
`schwab`	Charles Schwab	$0.00 / $0.65
`sofi-invest`	SoFi Invest	$0.00 / $0.00
`tastytrade`	Tastytrade	$0.00 / $1.00
`td-ameritrade`	TD Ameritrade (Schwab)	$0.00 / $0.65
`trade-station`	TradeStation	$0.00 / $0.50
`tradier`	Tradier	$0.0035 per share / $0.35
`vanguard`	Vanguard	$0.00 / $1.00
`webull`	Webull	$0.00 / $0.00

Create Portfolio

Create a new portfolio for an account. Each account can have multiple portfolios with different configurations.

Request Body Parameters

Parameter	Type	Description	Required
`accountId`	String	Account ID (UUID)	Yes
`portfolioType`	String	Portfolio type: CASH or MARGIN	Yes
`accountType`	String	Account type: INDIVIDUAL, IRA, or ROTH_IRA	Yes
`brokerId`	String	Broker configuration ID (see Available Brokers below)	Yes
`marginType`	String	Margin type: REG_T or PORTFOLIO (for MARGIN portfolios)	No
`portfolioMarginEngineType`	String	Engine type: SIMPLE, SPAN, or TIMS (for PORTFOLIO margin)	No

Request

POST

/v1/accounts/portfolios

curl -X POST https://api.paperinvest.io/v1/accounts/portfolios \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "portfolioType": "MARGIN",
    "accountType": "INDIVIDUAL",
    "brokerId": "default",
    "marginType": "REG_T"
  }'

Response

201 Created

{
  "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "portfolioType": "MARGIN",
  "accountType": "INDIVIDUAL",
  "brokerId": "default",
  "marginType": "REG_T",
  "settledCash": 100000,
  "pendingCash": 0,
  "reservedCash": 0,
  "longMarketValue": 0,
  "shortMarketValue": 0,
  "totalEquity": 100000,
  "marginLoan": 0,
  "maintenanceMarginRequirement": 0,
  "initialMarginRequirement": 0,
  "overnightBuyingPower": 200000,
  "dayTradeBuyingPower": 400000,
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-01T12:00:00Z"
}

Get Portfolio

Retrieve detailed information about a specific portfolio.

Path Parameters

Parameter	Type	Description	Required
`portfolioId`	String	The portfolio ID (UUID)	Yes

Request

GET

/v1/accounts/portfolios/:portfolioId

curl -X GET https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "portfolioType": "MARGIN",
  "accountType": "INDIVIDUAL",
  "brokerId": "default",
  "marginType": "REG_T",
  "settledCash": 100000.00,
  "pendingCash": 500.25,
  "reservedCash": 250.75,
  "longMarketValue": 50000.00,
  "shortMarketValue": 0,
  "totalEquity": 150249.50,
  "marginLoan": 0,
  "smaBalance": 25000.00,
  "fedRequirement": 25000.00,
  "houseRequirement": 25000.00,
  "overnightBuyingPower": 300499.00,
  "dayTradeBuyingPower": 600998.00,
  "marginCallActive": false,
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-15T09:22:10.456Z"
}

Get Account Portfolios

Retrieve all portfolios for a specific account.

Path Parameters

Parameter	Type	Description	Required
`accountId`	String	The account ID (UUID)	Yes

Request

GET

/v1/accounts/:accountId/portfolios

curl -X GET https://api.paperinvest.io/v1/accounts/550e8400-e29b-41d4-a716-446655440000/portfolios \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

[
  {
    "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "portfolioType": "MARGIN",
    "accountType": "INDIVIDUAL",
    "brokerId": "default",
    "totalEquity": 150249.50,
    "settledCash": 100000.00
  },
  {
    "portfolioId": "9c83d2a1-b7e5-4f9c-8d3a-2e7f1c6b5a4d",
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "portfolioType": "CASH",
    "accountType": "ROTH_IRA",
    "brokerId": "fidelity",
    "totalEquity": 25000.75,
    "settledCash": 25000.75
  }
]

Get Portfolio Equities

Get all equity positions in a portfolio.

Request

GET

/v1/accounts/portfolios/:portfolioId/equities

curl -X GET https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a/equities \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

[
  {
    "symbol": "AAPL",
    "quantity": 100,
    "averageCost": 150.50,
    "lastPrice": 155.25,
    "marketValue": 15525.00,
    "unrealizedPnL": 475.00,
    "realizedPnL": 0,
    "todayPnL": 125.00,
    "settledQuantity": 100,
    "pendingQuantity": 0,
    "reservedQuantity": 0
  },
  {
    "symbol": "MSFT",
    "quantity": 50,
    "averageCost": 320.00,
    "lastPrice": 325.50,
    "marketValue": 16275.00,
    "unrealizedPnL": 275.00,
    "realizedPnL": 150.00,
    "todayPnL": -50.00,
    "settledQuantity": 50,
    "pendingQuantity": 0,
    "reservedQuantity": 0
  }
]

Get Portfolio Options

Get all option positions in a portfolio.

Request

GET

/v1/accounts/portfolios/:portfolioId/options

curl -X GET https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a/options \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

[
  {
    "symbol": "AAPL",
    "optionSymbol": "AAPL230120C00150000",
    "quantity": 10,
    "optionType": "CALL",
    "strike": 150.00,
    "expiration": "2023-01-20",
    "averageCost": 5.50,
    "lastPrice": 7.25,
    "marketValue": 7250.00,
    "unrealizedPnL": 1750.00,
    "deltaPerContract": 0.65,
    "gammaPerContract": 0.02,
    "thetaPerContract": -0.15,
    "vegaPerContract": 0.35
  }
]

Get Day Trade Activity

Get day trading activity for a portfolio. This endpoint has a higher rate limit (500 requests per minute) to support frequent polling.

Query Parameters

Parameter	Type	Description	Required
`page`	Number	Page number (default: 1)	No
`limit`	Number	Results per page (default: 50)	No

Request

GET

/v1/accounts/portfolios/:portfolioId/day-trades

curl -X GET https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a/day-trades \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "data": [
    {
      "symbol": "AAPL",
      "tradingDate": "2025-01-15",
      "buyTime": "2025-01-15T10:30:00Z",
      "sellTime": "2025-01-15T14:45:00Z",
      "quantity": 100,
      "buyPrice": 150.00,
      "sellPrice": 151.50,
      "pnl": 150.00,
      "isSameDay": true
    },
    {
      "symbol": "TSLA",
      "tradingDate": "2025-01-15",
      "buyTime": "2025-01-15T09:45:00Z",
      "sellTime": "2025-01-15T15:30:00Z",
      "quantity": 50,
      "buyPrice": 240.00,
      "sellPrice": 242.50,
      "pnl": 125.00,
      "isSameDay": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "totalPages": 1
  }
}

Update Portfolio Broker

Switch the broker configuration for a portfolio. This affects commission rates, trading hours, order types, and other broker-specific restrictions.

Request Body Parameters

Parameter	Type	Description
`brokerId`	string	The broker configuration ID to switch to (see Available Brokers)

Request Example

curl -X PUT https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a/broker \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerId": "robinhood"
  }'

Response Example

200 OK

{
  "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "portfolioType": "MARGIN",
  "accountType": "INDIVIDUAL",
  "brokerId": "robinhood",
  "marginType": "REG_T",
  "settledCash": 100000.00,
  "pendingCash": 0,
  "reservedCash": 0,
  "longMarketValue": 50000.00,
  "shortMarketValue": 0,
  "totalEquity": 150000.00,
  "marginLoan": 0,
  "overnightBuyingPower": 300000.00,
  "dayTradeBuyingPower": 600000.00,
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-15T14:30:00Z"
}

Error Responses

Conflict

409 Conflict

{
  "statusCode": 409,
  "message": "Cannot change broker while there are open orders",
  "error": "Conflict"
}

Bad Request

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid broker ID. Must be one of: default, ally-invest, alpaca, cobra-trading, ...",
  "error": "Bad Request"
}

Check Portfolio Margin Eligibility

Check if a portfolio is eligible for portfolio margin upgrade.

Request

GET

/v1/accounts/portfolios/:portfolioId/margin-eligibility

curl -X GET https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a/margin-eligibility \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "eligible": true,
  "totalEquity": 150249.50,
  "requiredEquity": 100000.00,
  "reasons": [],
  "currentMarginType": "REG_T",
  "availableEngines": ["SIMPLE", "SPAN", "TIMS"]
}

Ineligible Response

200 OK

{
  "eligible": false,
  "totalEquity": 50000.00,
  "requiredEquity": 100000.00,
  "reasons": [
    "Total equity must be at least $100,000 (current: $50,000)"
  ],
  "currentMarginType": "REG_T"
}

Upgrade Portfolio Margin

Upgrade a portfolio's margin type from Reg T to Portfolio Margin.

Request Body Parameters

Parameter	Type	Description	Required
`marginType`	String	Margin type: REG_T or PORTFOLIO	Yes
`portfolioMarginEngineType`	String	Engine type: SIMPLE, SPAN, or TIMS (for PORTFOLIO margin)	No
`addPromotionalCash`	Boolean	Add $150,000 promotional cash for demo purposes	No

Request

PUT

/v1/accounts/portfolios/:portfolioId/margin-upgrade

curl -X PUT https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a/margin-upgrade \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "marginType": "PORTFOLIO",
    "portfolioMarginEngineType": "TIMS",
    "addPromotionalCash": true
  }'

Response

200 OK

{
  "success": true,
  "portfolio": {
    "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
    "marginType": "PORTFOLIO",
    "portfolioMarginEngineType": "TIMS",
    "settledCash": 250000.00
  },
  "message": "Portfolio upgraded to PORTFOLIO margin",
  "promotionalCashAdded": 150000
}

Reset Portfolio

Reset a portfolio to its initial state. This will close all positions and reset the cash balance.

Request Body Parameters

Parameter	Type	Description	Required
`confirmReset`	Boolean	Must be true to confirm the reset	Yes

Request

POST

/v1/accounts/portfolios/:portfolioId/reset

curl -X POST https://api.paperinvest.io/v1/accounts/portfolios/8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a/reset \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmReset": true
  }'

Response

200 OK

{
  "success": true,
  "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
  "message": "Portfolio reset successfully",
  "resetSummary": {
    "positionsClosed": 5,
    "ordersCancelled": 3,
    "newCashBalance": 100000.00,
    "oldCashBalance": 150249.50,
    "realizedPnL": -5249.50
  }
}

Portfolio Types and Restrictions

Cash vs Margin Portfolios

Cash Portfolios: Can only use settled cash for trading. No leverage available.
Margin Portfolios: Can borrow against securities for additional buying power.

Account Type Restrictions

IRA/Roth IRA: Must be cash portfolios (margin not allowed)
Individual: Can be either cash or margin

Margin Types

Reg T (Regulation T): Standard margin with 2x overnight buying power
Portfolio Margin: Risk-based margin with potentially higher leverage

Error Handling

Validation Error

400 Bad Request

{
  "statusCode": 400,
  "message": [
    "portfolioType must be either CASH or MARGIN",
    "accountType must be one of: INDIVIDUAL, IRA, ROTH_IRA"
  ],
  "error": "Bad Request"
}

Not Found

404 Not Found

{
  "statusCode": 404,
  "message": "Portfolio not found",
  "error": "Not Found"
}

Portfolio

Overview

API Endpoints Overview

Available Brokers

Create Portfolio

Request Body Parameters

Request

Response

Get Portfolio

Path Parameters

Request

Response

Get Account Portfolios

Path Parameters

Request

Response

Get Portfolio Equities

Request

Response

Get Portfolio Options

Request

Response

Get Day Trade Activity

Query Parameters

Request

Response

Update Portfolio Broker

Request Body Parameters

Request Example

Response Example

200 OK

Error Responses

Conflict

Bad Request

Check Portfolio Margin Eligibility

Request

Response

Ineligible Response

Upgrade Portfolio Margin

Request Body Parameters

Request

Response

Reset Portfolio

Request Body Parameters

Request

Response

Portfolio Types and Restrictions

Cash vs Margin Portfolios

Account Type Restrictions

Margin Types

Error Handling

Validation Error

Not Found

See Also