> For the complete documentation index, see [llms.txt](https://blackboard-fi.gitbook.io/blackboard-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://blackboard-fi.gitbook.io/blackboard-docs/trade/aster-api.md).

# API Trading via Aster

Blackboard's crypto perpetuals run on [Aster](https://www.asterdex.com). The Crypto Account in your Blackboard account is an ordinary Aster account, owned by your Blackboard wallet. Export that wallet's key, register an API agent with it, and you can trade the same account from your own code.

Orders you send with Blackboard's builder code are credited exactly like orders placed in the app. Because it is one account, your bot's positions and orders also appear in the Blackboard terminal.

{% hint style="warning" %}
**Blackboard does not recommend trading this way.** Use the app unless you need to automate. Through the API you handle your wallet key and set the builder fee yourself. Any builder fee you pay above the rate for your tier counts toward your Board Points, but it is not eligible for a refund. See [Builder fee by tier](#builder-fee-by-tier).
{% endhint %}

## At a Glance

|                                 |                                                                    |
| ------------------------------- | ------------------------------------------------------------------ |
| Aster `user`                    | Your Blackboard wallet address, shown as **EOA (EVM)** in Settings |
| Builder address                 | `0xecD0674915473B0F2D9061dc6a004f18E29a882E`                       |
| `feeRate` to attach to orders   | `0.00025` (0.025%)                                                 |
| Approved ceiling (`maxFeeRate`) | `0.001` (0.1%), set when you enable trading in the app             |
| Network                         | Aster mainnet, API v3 (`https://fapi.asterdex.com`)                |

Rates are decimal fractions, not percentages: `0.00025` is 0.025%, or 2.5 bps.

## How Crediting Works

Aster reports to each builder the fills that carried its code. Blackboard reads that report and matches each fill to the Blackboard account that owns the wallet. A fill is credited when:

1. The order was placed on your Blackboard wallet's Aster account.
2. The order carried `builder` and a `feeRate` at or above the rate for your fee tier.

Credited volume counts toward your rolling 30-day fee tier, the leaderboard and trading competitions, together with anything you trade in the app.

The builder fee is charged by Aster on every fill, maker or taker, on top of Aster's own trading fee, and is paid to Blackboard. It is the same fee the app attaches to your orders.

## Step 1: Create Your Account and Enable Crypto Trading

1. Sign up at [app.blackboard.fi](https://app.blackboard.fi). Your account comes with a Blackboard wallet.
2. Deposit, and move funds into your **Crypto Account**.
3. Open any market under **Crypto** and press **Enable Trading**.

Enable Trading sets up the Aster account and approves Blackboard as a builder on it, with a ceiling of `0.001`. You do this once.

## Step 2: Export Your Wallet Key

In the app, open **Settings → Account → Export keys**, acknowledge the warning, and continue. The key shown belongs to the address listed as **EOA (EVM)** on the same screen. That address is your Aster `user`.

{% hint style="danger" %}
This key controls your whole Blackboard wallet: every chain and every venue, not only Aster. It cannot be changed. Anyone who has it can take your funds. Blackboard never asks for it.
{% endhint %}

## Step 3: Register an API Agent

Aster's API signs orders with an agent key (`signer`), not with the wallet key. Use the wallet key once to authorize an agent, then store it offline. Your bot only ever needs the agent key.

Either route works:

* **On Aster's site.** Import the exported key into a wallet such as MetaMask, connect at [asterdex.com/en/api-wallet](https://www.asterdex.com/en/api-wallet), switch to **Pro API**, and create an API wallet.
* **By script.** Sign `ApproveAgent` with the wallet key and send `POST /fapi/v3/approveAgent`. Aster's [`01_approveAgent.js`](https://github.com/asterdex/API-demo/tree/main/aster-code-demo) does this.

When you create the agent:

* Allow perpetual trading and leave withdrawals off (`canPerpTrade=true`, `canWithdraw=false`).
* Set an IP whitelist and an expiry.
* Leave the agents you did not create in place. The Blackboard app uses them, and removing one means running Enable Trading again.

## Step 4: Add Two Parameters to Every Order

Sign and send orders the way Aster's API documents, with two more parameters in the signed parameter string:

| Parameter | Value                                        |
| --------- | -------------------------------------------- |
| `builder` | `0xecD0674915473B0F2D9061dc6a004f18E29a882E` |
| `feeRate` | `0.00025`                                    |

```
symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=0.01&price=60000
  &builder=0xecD0674915473B0F2D9061dc6a004f18E29a882E&feeRate=0.00025
  &nonce=...&user=...&signer=...
```

* Both parameters are required together, on every order you want credited, including closing, reduce-only and TP/SL orders.
* Send `feeRate` as a plain decimal string. Some languages print small numbers as `2.5e-4`.
* `POST /fapi/v3/order` and `POST /fapi/v3/placeStrategyOrder` accept them. Aster's documentation does not list them for batch orders, so test before relying on that.
* An order without the code is an ordinary Aster trade. It fills normally and is not credited. Nothing is credited after the fact.

{% hint style="info" %}
Aster's `09_placeOrder.js` demo sends a live market order for 0.03 BTC with a hardcoded `feeRate`. Edit the symbol, size and rate before running it.
{% endhint %}

## Step 5: Check That It Works

1. `GET /fapi/v3/builder` (agent-signed, no parameters) lists your approvals. Expect a row with `builderAddress` equal to the Blackboard address and `maxFeeRate` `0.001`.
2. Place a small order with the two parameters. It shows up in the Blackboard terminal right away, since it is the same account.
3. Credited fills then count in your leaderboard figures and, during an event, your competition standing. Fills are collected every few minutes, but totals can take up to a day to update.

Seeing the order in the terminal confirms the account, not the credit. Only orders that carried the code are credited.

## Builder Fee by Tier

Your tier follows your rolling 30-day volume. Thresholds are on the [Fees page](/blackboard-docs/resources/fees.md).

| Tier      | Builder fee | `feeRate` |
| --------- | ----------- | --------- |
| Bronze    | 0.025%      | `0.00025` |
| Silver    | 0.022%      | `0.00022` |
| Gold      | 0.019%      | `0.00019` |
| Platinum  | 0.017%      | `0.00017` |
| Diamond   | 0.003%      | `0.00003` |
| Legendary | 0.003%      | `0.00003` |

A fill whose builder fee is below your tier's rate does not count as qualifying volume. Not sure of your tier? Attach `0.00025`: it qualifies at every tier.

Aster charges whatever `feeRate` you attach, up to your approved ceiling. If that is more than your tier's rate, the extra builder fee counts toward your Board Points. It is not eligible for a refund.

## What Does Not Get Credited

* Orders sent without `builder` and `feeRate`.
* Fills with a builder fee below your tier's rate.
* Trades on any Aster account other than your Blackboard wallet's.
* Accounts with Aster's privacy mode on. Aster does not share those accounts' trades with builders, so there is nothing for Blackboard to read.
* Testnet trades.

Fills on your account that lack the code, or carry a lower rate, are still visible to Blackboard and may be reviewed during a trading competition.

## Sharing One Account Between the App and Your Bot

* Balance, positions and open orders are common. An order from either side uses the same margin.
* Leverage, margin mode and position mode are account settings. Changing one through the API changes it in the app.
* Deposit and withdraw through the app.

## Troubleshooting

| Symptom                                                                       | Check                                                                                                                                                      |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Order rejected with a builder error such as `-2031 INVALID_BUILDER_PARAMETER` | Enable Trading was completed (`GET /fapi/v3/builder` lists Blackboard), both parameters are sent, the address is exact, and `feeRate` is `0.001` or lower. |
| Signature errors on orders                                                    | You are signing with the agent key, `user` is the Blackboard wallet address, `signer` is the agent address, and the nonce is fresh.                        |
| The app asks you to Enable Trading again                                      | An agent Blackboard created was removed, or the builder approval was revoked. Run Enable Trading; your own agent is unaffected.                            |
| Orders fill but nothing is credited                                           | The list above, then allow up to a day.                                                                                                                    |

## Security

* Use the wallet key once, to register the agent. Keep it offline afterwards and never put it in your bot.
* Give the agent no withdrawal permission, and restrict it to your server's IP.
* The wallet key cannot be rotated. If it leaks, withdraw your funds and stop using the account.
* Approving Blackboard as a builder lets Aster pay Blackboard a fee, up to `0.001`, on orders that name it. It does not let Blackboard place orders, withdraw, or move funds. It does let the builder read the account's trades, orders, positions and balances through Aster's builder API, which is how your volume is credited.

## Appendix: Approving the Builder by API

Enable Trading in the app already does this. If you need to do it yourself, it is an EIP-712 signature from the wallet key (an agent cannot sign it):

```json
{
  "domain": {
    "name": "AsterSignTransaction",
    "version": "1",
    "chainId": 56,
    "verifyingContract": "0x0000000000000000000000000000000000000000"
  },
  "primaryType": "ApproveBuilder",
  "types": {
    "ApproveBuilder": [
      { "name": "Builder", "type": "string" },
      { "name": "MaxFeeRate", "type": "string" },
      { "name": "BuilderName", "type": "string" },
      { "name": "AsterChain", "type": "string" },
      { "name": "User", "type": "string" },
      { "name": "Nonce", "type": "uint256" }
    ]
  },
  "message": {
    "Builder": "0xecD0674915473B0F2D9061dc6a004f18E29a882E",
    "MaxFeeRate": "0.001",
    "BuilderName": "Blackboard",
    "AsterChain": "Mainnet",
    "User": "<your wallet address>",
    "Nonce": "<current time in microseconds>"
  }
}
```

Send `POST /fapi/v3/approveBuilder`, form-encoded, with the same values under their camelCase names plus the signature:

```
builder, maxFeeRate, builderName, asterChain, user, nonce, signature, signatureChainId=56
```

Four details cause most failed signatures (`-1000 Signature check failed`):

* Field names are capitalized in the typed data and camelCase in the request.
* `Builder` and `User` are typed `string`, not `address`. Only `Nonce` is `uint256`.
* The chain id is `56` for this signature, even though order signatures use `1666`.
* Field order in `types` must match the list above.

Aster's [`05_approveBuilder.js`](https://github.com/asterdex/API-demo/tree/main/aster-code-demo) does the same thing. `UpdateBuilder` (`POST /fapi/v3/updateBuilder`) changes the ceiling and `DelBuilder` (`DELETE /fapi/v3/builder`) revokes it; revoking stops the app from trading Crypto until you enable trading again.

## References

* Aster API documentation: [futures API v3](https://github.com/asterdex/api-docs/blob/master/V3%28Recommended%29/EN/aster-finance-futures-api-v3.md)
* Aster builder demos: [JavaScript](https://github.com/asterdex/API-demo/tree/main/aster-code-demo), [Python](https://github.com/asterdex/api-docs/blob/master/demo/aster-code.py)
* Support: <support@blackboard.fi>

## Next Steps

* [Fees](/blackboard-docs/resources/fees.md) — fee tiers and 30-day volume thresholds
* [Crypto Perpetuals](/blackboard-docs/trade/perpetual-trading/crypto-perpetuals.md) — how crypto perpetuals work on Blackboard
* [Security](/blackboard-docs/account/security.md) — keeping your wallet safe