Tenants and accounts

Every trading action in Plurex happens on an account, and every account belongs to a tenant. This page explains both, how accounts are created on real and paper hosts, and which account operations are safe to retry.

Tenants

The tenant is the owner of your trading resources. Every account belongs to exactly one tenant, and your API keys are created under it.

Find your tenant ID next to your API keys on the DevTools page of the Plurex app.
API keys act as the tenant. A request signed with your X-API-KEY and X-API-SECRET has full access to the tenant’s accounts.
Tenant-wide operations take a tenantId: Connect, List accounts and Create a paper account.

See Authentication for creating keys and sending them.

Accounts

An account is your account on one host. It lives on exactly one host for its whole life, and every operation on it takes only its accountId: Plurex resolves the host and checks your access from the account itself. You never pass a hostId or tenantId to trade.

{
  "id": "acc_7f3c2a91",
  "tenantId": "ten_4b8e10d2",
  "hostId": "bybit",
  "isPaper": false,
  "name": "Main Bybit",
  "credential": { "publicValue": "Xk29fLq8TzQ1vB7c", "credentialType": "ApiKey" }
}

credential.publicValue is the non-secret part of the credential, such as the API key, so you can tell which key an account uses. The secret is never returned. For a paper account publicValue is null and credentialType is Paper.

Real and paper accounts

	Real account	Paper account
Host	A real host, such as `bybit` or `valr`	A paper host, such as `bybit-paper` or `valr-paper`
Created with	Connect, using the exchange’s API credentials	Create a paper account
`isPaper`	`false`	`true`
Money	Real funds on the exchange	Simulated balances you add with Deposit
Trading	Every hosts operation	The same hosts operations
Managed with	List, Get, Rename, Delete	List, Get, Rename, Delete

Creation is the only part that differs: connecting an account links an existing exchange account, while creating a paper account starts a new simulation. After that, both kinds are traded and managed through the same operations, so code written against a paper account runs against a real one by switching the accountId. Read each host’s capabilities before you switch, because paper and real hosts publish their own. See Going live.

Connecting an exchange account

Connect adds an exchange account using its API credentials. The host must list ApiKey in supportedCredentialTypes.

curl --request POST https://api.plurex.io/api/v1/accounts/command/Connect \
  --header 'Content-Type: application/json' \
  --header "X-API-KEY: $PLUREX_API_KEY" \
  --header "X-API-SECRET: $PLUREX_API_SECRET" \
  --data '{
    "tenantId": "'"$PLUREX_TENANT_ID"'",
    "name": "Main Bybit",
    "hostId": "bybit",
    "credential": {
      "type": "ApiKey",
      "publicKey": "YOUR_EXCHANGE_API_KEY",
      "secretKey": "YOUR_EXCHANGE_API_SECRET"
    }
  }'

Before connecting, Plurex checks the key with the host:

The key must allow reading and trading. Plurex needs to read your orders, balances and positions, and to place and cancel orders.
Bybit keys must belong to a Unified Trading Account.
A refused key creates no account. Connect verifies the key with the exchange and refuses it if the exchange rejects it or the key cannot read and trade. Retrying with the same key will not help: fix the key’s permissions at the exchange, or create a new key, then connect again.

To connect through the web app instead, see Add an exchange.

Creating a paper account

Create a paper account takes your tenantId, a name and the hostId of a paper host. Find paper hosts with List hosts: they have isPaper: true, and modelHostId names the real host each one simulates.

{
  "tenantId": "ten_4b8e10d2",
  "name": "BTC perp forward test",
  "hostId": "bybit-paper"
}

A new paper account starts with no balances; fund it with Deposit. The number of paper accounts may be limited by your plan; at the limit, the call returns 422 AccountLimit. See Paper trading.

Account lifecycle

Operation	What it does	Takes
Connect	Connects an exchange account.	`tenantId`, `name`, `hostId`, `credential`
Create a paper account	Creates a paper account on a paper host.	`tenantId`, `name`, `hostId`, optional `feeTier`
Update credentials	Replaces a connected account’s exchange credentials, for example when you rotate keys. The new key is checked like a new connection, but Plurex does not check that it belongs to the same exchange account, so use a key for that account.	`accountId`, `credential`
Rename	Changes the account’s name.	`accountId`, `name`
Delete	Removes the account from Plurex.	`accountId`
List accounts	Lists the tenant’s accounts, optionally only on some hosts (`hostIds`) or only paper or real (`isPaper`). Paged: follow `nextCursor` until it is `null`.	`tenantId`, optional filters
Get an account	Returns one account.	`accountId`

For example, to list only your paper accounts:

{
  "tenantId": "ten_4b8e10d2",
  "isPaper": true
}

Retry safety

A timeout or 5xx does not prove that a command had no effect. Each account operation tells you how to recover:

Operation	Safe to repeat?	If the outcome is unclear
Connect	No: repeating connects another account.	Check List accounts for an account on that `hostId` whose `credential.publicValue` is the key you sent, before retrying.
Create a paper account	No: repeating creates another account.	Check List accounts for a new account on that `hostId` before retrying.
Update credentials	Yes, with the same values.	Repeat it.
Rename	Yes, with the same values.	Repeat it.
Delete	Not after success: a repeat returns an error, because the account no longer exists.	Check List accounts; if the account is gone, the delete succeeded.
List, Get	Yes: reads change nothing.	Repeat them.

Identify the new account by what it is, not by its name: after an unclear Connect, look for an account on the hostId you sent whose credential.publicValue is the exchange key you sent; after an unclear Create, compare the list for that paper hostId with the accounts you already knew about. Names are labels for you; don’t rely on them to tell accounts apart.

Errors to expect

Code	Status	Meaning
`AccountNotFound`	404	The `accountId` does not exist.
`Forbidden`	403	You are authenticated but have no access to that account or operation.
`AccountLimit`	422	An account or subscription limit was reached.

See Errors for the full list.

Venues and hosts for where accounts fit.
Authentication for API keys.
Add an exchange to connect an account in the web app.
Paper trading to create, fund and trade paper accounts.

Get started

Concepts

Capabilities

Trading guides

Paper trading

Web app

Tenants

Accounts

Real and paper accounts

Connecting an exchange account

Creating a paper account

Account lifecycle

Retry safety

Errors to expect

​Tenants

​Accounts

​Real and paper accounts

​Connecting an exchange account

​Creating a paper account

​Account lifecycle

​Retry safety

​Errors to expect

​Related

Tenants

Accounts

Real and paper accounts

Connecting an exchange account

Creating a paper account

Account lifecycle

Retry safety

Errors to expect

Related