> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plurex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenants and accounts

> Who owns your accounts, how real and paper accounts are created, and how to manage them safely through the API.

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](https://docs.plurex.io/api-reference/platform/accounts/connect.md), [List accounts](https://docs.plurex.io/api-reference/platform/accounts/list.md) and [Create a paper account](https://docs.plurex.io/api-reference/platform/paper/create.md).

See [Authentication](https://docs.plurex.io/authentication.md) 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.

```json theme={null}
{
  "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](https://docs.plurex.io/api-reference/platform/accounts/connect.md), using the exchange's API credentials | [Create a paper account](https://docs.plurex.io/api-reference/platform/paper/create.md) |
| `isPaper` | `false` | `true` |
| Money | Real funds on the exchange | Simulated balances you add with [Deposit](https://docs.plurex.io/api-reference/platform/paper/deposit.md) |
| 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](https://docs.plurex.io/paper/going-live.md).

## Connecting an exchange account

[Connect](https://docs.plurex.io/api-reference/platform/accounts/connect.md) adds an exchange account using its API credentials. The host must list `ApiKey` in `supportedCredentialTypes`.

```bash theme={null}
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](https://docs.plurex.io/platform/add-exchange.md).

## Creating a paper account

[Create a paper account](https://docs.plurex.io/api-reference/platform/paper/create.md) takes your `tenantId`, a `name` and the `hostId` of a **paper** host. Find paper hosts with [List hosts](https://docs.plurex.io/api-reference/platform/hosts/list.md): they have `isPaper: true`, and `modelHostId` names the real host each one simulates.

```json theme={null}
{
  "tenantId": "ten_4b8e10d2",
  "name": "BTC perp forward test",
  "hostId": "bybit-paper"
}
```

A new paper account starts with no balances; fund it with [Deposit](https://docs.plurex.io/api-reference/platform/paper/deposit.md). The number of paper accounts may be limited by your plan; at the limit, the call returns `422 AccountLimit`. See [Paper trading](https://docs.plurex.io/paper/overview.md).

## Account lifecycle

| Operation | What it does | Takes |
| - | - | - |
| [Connect](https://docs.plurex.io/api-reference/platform/accounts/connect.md) | Connects an exchange account. | `tenantId`, `name`, `hostId`, `credential` |
| [Create a paper account](https://docs.plurex.io/api-reference/platform/paper/create.md) | Creates a paper account on a paper host. | `tenantId`, `name`, `hostId`, optional `feeTier` |
| [Update credentials](https://docs.plurex.io/api-reference/platform/accounts/update-connection.md) | 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](https://docs.plurex.io/api-reference/platform/accounts/rename.md) | Changes the account's name. | `accountId`, `name` |
| [Delete](https://docs.plurex.io/api-reference/platform/accounts/delete.md) | Removes the account from Plurex. | `accountId` |
| [List accounts](https://docs.plurex.io/api-reference/platform/accounts/list.md) | 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](https://docs.plurex.io/api-reference/platform/accounts/get.md) | Returns one account. | `accountId` |

For example, to list only your paper accounts:

```json theme={null}
{
  "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](https://docs.plurex.io/api-reference/platform/accounts/list.md) 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](https://docs.plurex.io/api-reference/platform/accounts/list.md) 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](https://docs.plurex.io/api-reference/platform/accounts/list.md); 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](https://docs.plurex.io/api-reference/platform/errors.md) for the full list.

## Related

* [Venues and hosts](https://docs.plurex.io/concepts/venues-and-hosts.md) for where accounts fit.
* [Authentication](https://docs.plurex.io/authentication.md) for API keys.
* [Add an exchange](https://docs.plurex.io/platform/add-exchange.md) to connect an account in the web app.
* [Paper trading](https://docs.plurex.io/paper/overview.md) to create, fund and trade paper accounts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.