> For the complete documentation index, see [llms.txt](https://docs.canborsa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.canborsa.com/getting-started/api.md).

# API

The Canborsa API lets you connect bots, scripts, AI agents and your own tools to your Canborsa account. You can read market data, check balances and positions, and trade spot and perpetuals programmatically, 24/7.

### In short

* **Up to 20 API keys per account.** Each key has its own permissions and can be restricted to a list of IP addresses.
* **Three permission levels.** Read, Spot Trading and Perpetual Futures Trading.
* **Signed requests.** Every request is signed with HMAC, and each signature can be used only once.
* **Trading only, no money movement.** Withdrawals, deposits and API key management are not available through the API.
* **AI agents through MCP.** Claude, Cursor and other MCP clients can read markets and trade with your API key.
* **Partner API.** Referral partners can pull their referrals, campaigns and volume.
* **Full reference** with an OpenAPI spec and examples in Python, Node.js, Go and Shell at [app.canborsa.com/api-docs](https://app.canborsa.com/api-docs).

### Creating an API key

You create and manage keys on the API Management page in your account menu ([app.canborsa.com/api-management](https://app.canborsa.com/api-management)).

1. Open API Management and choose to create a new key.
2. Pick the permissions the key needs.
3. Optionally restrict the key to a list of IP addresses.
4. Confirm your login again with a wallet signature, an email code or a passkey.
5. Copy the secret. It is shown only once, together with a QR code, so store it somewhere safe right away.

You get an email every time a new key is created on your account. Confirming your login is also required whenever you extend the permissions of an existing key.

#### Permissions

| Permission                | What the key can do                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Read                      | View markets, balances, positions, orders and history                                                          |
| Spot Trading              | Everything in Read, plus swaps                                                                                 |
| Perpetual Futures Trading | Everything in Read, plus opening, increasing, reducing and closing perpetual positions, limit orders and TP/SL |

Give each key only the permissions it needs. A portfolio tracker only needs Read, while a trading bot needs a trading permission.

### What the API covers

The API gives your tools the same trading actions you have in the app, across all spot and perpetual markets on Canborsa.

| What the key can do      | Available through the API                                                 |
| ------------------------ | ------------------------------------------------------------------------- |
| Markets                  | Market data for spot and perpetual pairs                                  |
| Account                  | Balances, open positions, orders and trade history                        |
| Perpetuals               | Open, increase, reduce and close positions, place limit orders, set TP/SL |
| Swaps                    | Exchange supported assets at live prices                                  |
| Withdrawals and deposits | Not available                                                             |
| API key management       | Not available, keys are managed only in the app                           |

Because withdrawals and deposits are not part of the API, a key can trade on your account but can never move funds out of it.

### Signed requests and limits

Every request to the API is signed with your key's secret using HMAC. The exact headers, the string to sign and ready-made signing code are in the [API reference](https://app.canborsa.com/api-docs).

* **One-time signatures.** Each signature is valid for a single request, so a captured request cannot be replayed.
* **Rate limits.** Limits apply both per key and per account. The current values are listed in the reference.
* **IP restrictions you can rely on.** The client IP is taken only from requests that arrive through Cloudflare, so it cannot be spoofed to get around an IP allowlist.

### MCP server for AI agents

Canborsa runs an MCP server, so AI tools that support the Model Context Protocol, such as Claude and Cursor, can work with your account directly. The agent reads market data and trades using an API key you create.

The agent can do exactly what its key allows. Start with a Read key to let it analyse markets and your positions, and give it a trading permission only when you want it to place orders. Connection steps for each client are in the [API reference](https://app.canborsa.com/api-docs).

An AI agent can make mistakes like any other strategy. Review what it does, keep the key's permissions as narrow as possible and restrict it to your IP address.

### Partner API

Referral partners can use the API to track their results without opening the app. Through the Partner API you get your list of referrals, your campaigns and a summary of their activity, including spot trades and trading volume.

You can tag a campaign link with a `sub` label to separate traffic from different sources, for example one label per channel or creator, and see the results for each label through the API. Referral rewards themselves follow the regular [Referral Program](https://canborsa.com/referral-terms) rules.

### Security

These rules apply to every key automatically.

* Creating a key or extending its permissions requires confirming your login with a wallet signature, an email code or a passkey.
* You receive an email for every new key created on your account.
* A trading key that is not restricted to an IP list stops working after 14 days without use.
* Log out on all devices deletes all of your API keys along with your sessions.

#### Best practices

* Use a separate key for each bot, app or integration, so you can revoke one without affecting the others.
* Give a key only the permissions it needs, and use Read for trackers and analytics.
* Restrict trading keys to the IP addresses of your servers.
* Never share your secret or commit it to code repositories. Anyone with the secret can trade on your account within the key's permissions.
* Delete keys you no longer use.

**Warning.** A key with Spot Trading permission can swap your entire balance, and a key with Perpetual Futures Trading permission can open leveraged positions. Connect your keys only to tools you trust. Trading with leverage carries a high level of risk, and automated strategies can lose money as quickly as manual ones.

### API reference

The full reference lives at [app.canborsa.com/api-docs](https://app.canborsa.com/api-docs). It lists every endpoint with its parameters and responses, includes the OpenAPI specification you can import into your own tools, and shows ready-to-run examples in Python, Node.js, Go and Shell.

The reference is available in 12 languages. To get started, create a key on the [API Management](https://app.canborsa.com/api-management) page and follow the quick start in the reference.
