---
title: "Create Agent Portfolio (v2)"
method: POST
path: "/api/v2/agent-portfolios"
tags: ["Agent Portfolios"]
---

# Create Agent Portfolio (v2)

`POST /api/v2/agent-portfolios`

**Rate limit:** 60 requests per 60 seconds. This is the **default shared quota** — it is shared with every other endpoint that has no dedicated limit, so requests across those endpoints all draw from the same budget.

---

Creates a new agent-portfolio using scope names. Scopes are specified by name (scopeNames); scope ids are not supported in v2. IMPORTANT: investmentAmountInUsd is the amount deducted from YOUR (the caller's) account balance to copy-trade this agent-portfolio — it is NOT the agent-portfolio's own balance. Positions are mirrored proportionally: e.g. if you invest $2,000 and agentPortfolioVirtualBalance is $10,000, each position is copied at 20% of its size into your account.

## Headers

- `x-request-id` string, uuid, required
- `x-api-key` string, password, required
- `x-user-key` string, password, required

## Request body

- CreateAgentPortfolioV2Request
  - `investmentAmountInUsd` number, required — The amount in USD deducted from the CALLER's account balance to copy-trade this agent-portfolio. This is NOT the agent-portfolio's own balance — the agent-portfolio receives a separate fixed virtual balance (returned as agentPortfolioVirtualBalance). Positions are mirrored proportionally: e.g. $2,000 with a $10,000 virtual balance = 20% position sizing.
  - `agentPortfolioName` string, required — A unique display name for the agent-portfolio (6-10 characters).
  - `agentPortfolioDescription` string — An optional description of the agent-portfolio's purpose or strategy.
  - `userTokenName` string, required — A human-readable name for the user token provisioned with the agent-portfolio.
  - `scopeNames` string[], required — The set of permission scope names to grant to the provisioned user token. Available scopes: etoro-public:trade.real:read, etoro-public:trade.real:write, etoro-public:trade.demo:read, etoro-public:trade.demo:write.
  - `ipsWhitelist` string[] — An optional set of IPv4 addresses allowed to use the provisioned user token.
  - `expiresAt` string, date-time — An optional expiration date and time (UTC) for the provisioned user token.

## Response `201`

Agent-portfolio and user token created successfully

- CreateAgentPortfolioV2Response
  - `agentPortfolioId` string, uuid — The unique identifier of the newly created agent-portfolio.
  - `agentPortfolioName` string — The display name assigned to the agent-portfolio.
  - `agentPortfolioGcid` integer — The GCID associated with the agent-portfolio.
  - `agentPortfolioVirtualBalance` number — The fixed virtual balance (in USD) that the agent-portfolio was funded with. The investmentAmountInUsd used to copy is proportional to this balance.
  - `mirrorId` integer — The Trading API mirror ID for this agent-portfolio's copy trade.
  - `userTokens` CreateAgentPortfolioV2UserTokenItem[] — The user tokens generated during agent-portfolio creation.
    - `userTokenId` string, uuid — The unique identifier of the newly created user token.
    - `userToken` string — The generated user token secret. Only available at creation time.
    - `userTokenName` string — The user-defined name for the user token.
    - `clientId` string, uuid — The OAuth client identifier associated with the user token.
    - `ipsWhitelist` string[] — The set of whitelisted IP addresses authorized to use this token.
    - `scopes` ScopeNameItem[] — The permission scopes (by name) granted to this token.
      - `name` string — The permission scope name.
    - `expiresAt` string, date-time — The expiration date and time of the user token in UTC.

## Other responses

- `207` — Agent-portfolio created but user token provisioning failed
- `400` — Bad Request
- `401` — Unauthorized
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/etoro/apis/etoro-api.md) · [All operations](https://skmtc.net/etoro/apis/etoro-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/etoro/etoro-api/revisions/69c1fb266c35/schema)