### Understanding Amount & Position

There are a lot of powerful ways to express how large an order you'd like to place using either the amount setting, or position setting. Here we'll explain all the options and what the difference between amount and position is.

This will be mostly explained using examples. All the examples in this article will make the following assumptions...

• You are trading on BitMEX on the XBTUSD symbol
• You have a balance of 1 BTC, to keep the maths simpler.
• The Bitcoin price is \$10,000, also for simplicity
• You have your leverage slider at 10x
• You have an existing open position of 10,000 contracts using up 10% of your margin.
• A reminder that 1 contract is worth 1 dollar.

We'll also be using market orders in all the examples, but these settings work the same in all orders that support amount or position. Just remember that the calculations are made at the time the order is placed.

With that out of the way, lets start simple.

What is amount?

This is the amount to trade - the size of the order. It is not magically adjusted behind the scenes based on your leverage settings. It's just the amount, plain and simple. It is treated in a similar way to the Quantity field on BitMEX, if you were to manually enter your order size. The process is the same on other exchanges. It is measured in units of the base asset (contracts on BitMEX, dollars on Deribit, BTC on the BTC-EUR pair on coinbase etc)

What is position?

Position tells the bot what size you'd like your position to be after the order has been filled. When you look at your open position on BitMEX, your position size is shown in the size column. Again, this value isn't adjusted by the bot based on your current leverage settings. If you ask for a position size of 10, then you'll get a position size of 10 regardless of your current leverage settings. Because you are telling the bot what the final outcome will be, you don't need to say if you are buying or selling - the bot will work out to buy or sell based on your current position size and the desired position size.

On spot exchanges like Coinbase Pro and Bitfinex, this is treated as the amount of the asset you'd like in your balance. For example, on Bitfinex, using the BTCUSD pair, position would represent the amount of BTC you'd like in your balance after the order completes.

Quick summary of supported units

Unit Meaning on BitMEX or Deribit
50 50 contracts / dollars
50% 50% of your current balance, converted to contracts / dollars
50%% 50% of your available balance, in contracts / dollars
50%b Same as 50%
50%a Same as 50%%
50%p 50% of your current position size

Percentages are supported for both `position` and `amount` on Derbit and BitMEX. Spot exchanges like Bitfinex and Coinbase don't support percentages for position sizing, but see the notes below for more details...

#### Examples using amount and side

Again, remember that this examples are going to be based on the assumptions above.

Just buys 100 contracts, and doesn't take anything else into account.

``````myApiKeys(XBTUSD) {
}``````

Sell 100 contracts

Just sell 100 contracts.

``````myApiKeys(XBTUSD) {
market(side=sell, amount=100);
}``````

Our balance is 1 BTC, which at the current price is worth \$10,000. So, 50% of \$10,000 is \$5,000, so this will buy 5,000 contracts.

``````myApiKeys(XBTUSD) {
# could also use amount=50%b (the b meaning Balance)
}``````

Buy using 50% of my available margin

In this example, we have to refer to our current leverage - 10x in the example. The bot does not consider your current leverage in these calculations, you will need to be aware of your leverage settings and calculate a suitable size.

To use up 50% of our margin balance at 10x leverage, we need to buy 50 x 10 = 500% of our current balance. Our balance is \$10,000, so 500% of 10,000 is 50,000. This order will buy 50,000 contracts, based on the assumptions above.

``````myApiKeys(XBTUSD) {
# could also use amount=500%b (the b meaning Balance)
}``````

Buy 50% of my availabe balance

As we have an open position, some of our balance is locked up, leaving only \$9,000 worth available. 50% of 9,000 is 4,500, so our order will be for 4,500 contracts. Notice we are using `%%` instead of `%` to say we'd like to use Available Balance instead of Balance. We could also have used `%a`, for percentage of available balance.

``````myApiKeys(XBTUSD) {
# could also use amount=50%a (the a meaning Availabel Balance)
}``````

Sell 50% of my open position size

By using `%p`, we can tell the bot to calculate a percentage of our current open position size. In the assumptions above we said we have an open position of 10,000 contracts. 50% of 10,000 is 5,000, so this will sell 5,000 contracts.

``````myApiKeys(XBTUSD) {
market(side=sell, amount=50%p);
}``````

Double my open position size

By using `%p`, we can tell the bot to calculate a percentage of our current open position size. In the assumptions above we said we have an open position of 10,000 contracts. 100% of 10,000 is 10,000, so this will buy 10,000 contracts.

``````myApiKeys(XBTUSD) {
}``````

#### Examples using position

A reminder of the assumptions we are using for the calculations below...

• You are trading on BitMEX on the XBTUSD symbol
• You have a balance of 1 BTC, to keep the maths simpler.
• The Bitcoin price is \$10,000, also for simplicity
• You have your leverage slider at 10x
• You have an existing open position of 10,000 contracts using up 10% of your margin.
• A reminder that 1 contract is worth 1 dollar.

Our starting position was 10,000 contracts (see assumptions above), but we want it to be 5,000. The command below will work out the difference between where we are (10,000 long) and where we want to be (5,000 long). The result is to sell 5,000 contracts.

``````myApiKeys(XBTUSD) {
market(position=5000);
}``````

Close my open position

This example will close our current position, regardless of if we are long or short at the time, and regardless of our current position size.

Our starting position was 10,000 contracts, and our target size is 0 contracts. In this example it will sell 10,000 contracts, taking us down to zero.

``````myApiKeys(XBTUSD) {
market(position=0);
}``````

Adjust my position to 2,000 Short

Our starting position was 10,000 contracts (see assumptions above), but we want it to be -2,000. In the command below, the bot will work out the difference between where we are now (10,000) and where we want to be (-2,000). As a result, it will need to sell 12,000 contracts.

Remember that whatever our starting position size / direction, we'll always end up with 2,000 contracts short (-2,000) after this command

``````myApiKeys(XBTUSD) {
market(position=-2000);
}``````

Adjust my position to 50% of my balance

Our balance is \$10,000 (1 btc). 50% of 10,000 is 5,000. As our current position is already 10,000, this will sell 5,000 contracts.

``````myApiKeys(XBTUSD) {
market(position=50%);
}``````

Adjust my position so that I am short, using 50% of my available margin

In this example, we have to refer to our current leverage - 10x in the example. The bot does not consider your current leverage in these calculations, you will need to be aware of your leverage settings and calculate a suitable size.

To use up 50% of our margin balance at 10x leverage, we need to buy 50 x 10 = 500% of our current balance. As we want to be short, we'll ask for a position of -500%.

Our balance is \$10,000, so -500% of 10,000 is -50,000. As we want to end up with a position of -50,000, the bot also needs to take into account the current position size, which is +10,000 contracts (see assumptions).

To get from where we are now (+10,000) to where we want to be (-50,000), the bot will need to sell 60,000 contracts.

``````myApiKeys(XBTUSD) {
market(position=-500%);
}``````

Adjust my position to be 80% of its current size

Our current position is 10,000. 80% of our current position is 8,000. The bot needs to take us from our current position size of 10,000 to our target position size of 8,000, so it will sell 2,000 contracts

``````myApiKeys(XBTUSD) {
market(position=80%p);
}``````

Some images from Unsplash

#### Capture Charts

See a high quality chart with every alert, captured at the moment the alert was triggered. See exactly what the market was doing and make informed decisions.