v1

latestOpenAPI 3.0.12026-07-26171200932.8 KB

Agent Portfolios

Create Agent Portfolio (v2)

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.

post/api/v2/agent-portfolios

Headers

x-request-idstring uuid required

Example:63b556bf-c9e3-4052-96b8-405bef86f72e

A unique request identifier.

x-api-keystring password required

Example:lhgfaslk21490FAScVPkdsb53F9dNkfHG4faZSG5vfjndfcfgdssdgsdHF4663

API key for authentication.

x-user-keystring password required

Example:eyJlYW4iOiJVbnJlZ2lzdGVyZWRBcHBsaWNhdGlvbiIsImVrIjoiOE5sZ2cwcW5EUVdROUFNWGpXT2lmOWktZnpidG5KcUlqWGJ3WHJZZkpZcldrbG90ZEhvLVBjSWhQaU8xU1ZtMW84aU1WZGZqN2xWNzFjLXFxLmcybXE1dnh4Q1hUT25xaWRUaTFlcEhmVk1fIn0_

User-specific authentication key.

Request body

investmentAmountInUsdnumber 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.

agentPortfolioNamestring required

A unique display name for the agent-portfolio (6-10 characters).

agentPortfolioDescriptionstring

An optional description of the agent-portfolio's purpose or strategy.

userTokenNamestring required

A human-readable name for the user token provisioned with the agent-portfolio.

scopeNamesstring[] 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.

ipsWhiteliststring[]

An optional set of IPv4 addresses allowed to use the provisioned user token.

expiresAtstring date-time

An optional expiration date and time (UTC) for the provisioned user token.

Example request

{
  "investmentAmountInUsd": 2000,
  "agentPortfolioName": "MyPort1",
  "agentPortfolioDescription": "My trading portfolio",
  "userTokenName": "my-trading-token",
  "scopeNames": [
    "etoro-public:trade.real:read",
    "etoro-public:trade.real:write"
  ],
  "ipsWhitelist": [
    "192.168.1.1"
  ],
  "expiresAt": "2026-12-31T23:59:59Z"
}

Response

Agent-portfolio and user token created successfully

agentPortfolioIdstring uuid

The unique identifier of the newly created agent-portfolio.

agentPortfolioNamestring

The display name assigned to the agent-portfolio.

agentPortfolioGcidinteger

The GCID associated with the agent-portfolio.

agentPortfolioVirtualBalancenumber

The fixed virtual balance (in USD) that the agent-portfolio was funded with. The investmentAmountInUsd used to copy is proportional to this balance.

mirrorIdinteger

The Trading API mirror ID for this agent-portfolio's copy trade.

Example response

{
  "agentPortfolioId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agentPortfolioName": "MyPort1",
  "agentPortfolioGcid": 12345678,
  "agentPortfolioVirtualBalance": 10000,
  "mirrorId": 12345,
  "userTokens": [
    {
      "userTokenId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "userToken": "sk_live_a1b2c3d4e5f6...",
      "userTokenName": "my-trading-token",
      "clientId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "ipsWhitelist": [
        "192.168.1.1"
      ],
      "scopes": [
        {
          "name": "etoro-public:trade.real:read"
        }
      ],
      "expiresAt": "2026-12-31T23:59:59Z"
    }
  ]
}