3commas-io / 3commas-official-api-docs

Official Documentation for the 3commas APIs

Public Rest API for 3commas.io (2024-05-02)

General API Information

• Official Announcements regarding changes, downtime, etc. to the API will be reported here: https://t.me/commas_API

• We have telegram group where you can discuss any issues with API https://t.me/xcommas_api

• Streams, endpoints, parameters, payloads, etc. decscribed in the documents in this repository are considered official and supported.

• The use of any other streams, endpoints, parameters, or payloads, etc. is not supported; use them at your own risk and with no guarantees.

• The base endpoint is: https://api.3commas.io/public/api

• All endpoints return either a JSON object or array.

• PAIR format is QUOTE_BASE (for example USDT_BTC) for all exchanges (no matter what format the exchange is using).

• Data is returned in ascending order. Oldest first, newest last.

• All time and timestamp related fields are in seconds.

• HTTP 4XX return codes are used for malformed requests; the issue is on the sender's side.

• HTTP 429 return code is used when breaking a request rate limit.

• HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.

• HTTP 5XX return codes are used for internal errors; the issue is on 3commas's side.

• HTTP 504 return code is used when the API successfully sent the message

• Any endpoint can return an ERROR; the error payload is as follows:

{
  "error": "record_invalid",
  "error_description": "Invalid parameters",
  "error_attributes": {
    "api_key": [
      "is too short (minimum is 5 characters)"
    ],
    "secret": [
      "is too short (minimum is 5 characters)"
    ],
    "name": [
      "is too short (minimum is 2 characters)"
    ]
  }
}

• error field is mandatory. Specific error codes and messages defined in another document.
• error_description is localized extended description of error occurred. Optional.
• error_attributes used to show fields that didn't pass validations. Optional.
• For GET endpoints, parameters must be sent as a query string.
• For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded or application/json. You may mix parameters between both the query string and request body if you wish to do so.
• Parameters may be sent in any order.
• If a parameter sent in both the query string and request body, the query string parameter will be used.

Third-party implementations

• https://www.npmjs.com/package/3commas-api-node
• https://www.npmjs.com/package/3commas-typescript
• https://github.com/TheKimono/3Commas.Net
• https://github.com/bogdanteodoru/py3cw (Python 3.x implementation)

LIMITS

• A 429 will be returned when either rather limit is violated.
• Each route has a weight which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier weight.
• When a 429 is received, it's your obligation as an API to back off and not spam the API.
• Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (HTTP status 418).
• IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.

Endpoint security type

• Each endpoint has a security type that determines the how you will interact with it.
• API-keys are passed into the Rest API via the Apikey header.
• API-keys and secret-keys are case sensitive.
• API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for STATS only, while another API-key can access everything.

Security Type	Description
NONE	Endpoint can be accessed freely.
SIGNED	Endpoint requires sending a valid API-Key and signature.

SIGNED Endpoint security

• SIGNED endpoints require an additional header, Signature, to be sent.
• Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and uri?totalParams as the value for the HMAC operation.
• The signature is not case sensitive.
• totalParams is defined as the query string concatenated with the request body.

Look here for some examples

SIGNED Endpoint Examples for POST /public/api/ver1/users/change_mode

Here is a step-by-step example of how to send a valid signed payload from the Linux command line using echo, openssl, and curl.

Key	Value
api_key	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secret	NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j

Parameter	Value
mode	paper

Example 1: As a query string

• queryString: mode=paper

• HMAC SHA256 signature:

  [linux]$ echo -n "/public/api/ver1/users/change_mode?mode=paper" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
  (stdin)= bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316
  

• curl command:

  (HMAC SHA256)
  [linux]$ curl -H "Apikey: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -H "Signature: bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316" -X POST 'https://api.3commas.io/public/api/ver1/users/change_mode?mode=paper'
  

Example 2: As a request body

• requestBody: mode=paper

• HMAC SHA256 signature:

  [linux]$ echo -n "/public/api/ver1/users/change_mode?mode=paper" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
  (stdin)= bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316
  

• curl command:

  (HMAC SHA256)
  [linux]$ curl -H "Apikey: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -H "Signature: bca8d8c10acfbe8e76c5335d3efbe0a550487170a8bb7aaea0a13efabab55316" -X POST 'https://api.3commas.io/public/api/ver1/users/change_mode' -d 'mode=paper' 
  

Example 3: As a raw json

• requestBody: '{"mode": "paper"}'

• HMAC SHA256 signature:

  [linux]$ echo -n "/public/api/ver1/users/change_mode?{\"mode\": \"paper\"}" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
  (stdin)= 0475b407ba6f2388d213134e478b330f74073388a232737837f79018694ae373
  

• curl command:

  (HMAC SHA256)
  [linux]$ curl -H "Apikey: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -H "Signature: 0475b407ba6f2388d213134e478b330f74073388a232737837f79018694ae373" -H "Content-Type: application/json" -X POST 'https://api.3commas.io/public/api/ver1/users/change_mode' --data-raw '{"mode": "paper"}' 
  

SIGNED Endpoint Examples for GET /public/api/ver1/bots/{bot_id}/show

Here is a step-by-step example of how to test your endpoint through postman.

Once Postman works with the values, you can implement it in code.

Step 1: Set up GET url:

• With include_events: https://api.3commas.io/public/api/ver1/bots/EnterBotIdHere/show?include_events=true

By using include_events in the query string, in Postman, your Params field will be automatically filled in

Step 2: Calculate your Signature:

Use a HMAC SHA256 generator tool.

""	""
Input value	/public/api/ver1/bots/84512/show?include_events=true
Secret Key	Use your secret API key from 3commas
Hashed Output	Signature result to be used in Step 3

Step 3: Set up Headers:

Key	Value
Apikey	3commas API key goes here
Signature	Calculated Signature from Step 2 goes here

These 2 key/value pairs can be entered in Postman under Headers (which is located under the GET url field)

Step 4: Receive JSON object:

If you have followed these steps you should now receive a status 200 OK with your JSON data.

SIGNED Endpoint security (RSA)

Look here for more information about RSA key pair and how to compute signature for signed API requests.

API modes(real or paper)

By default, API mode(real or paper) synchronized with mode in web/app.

You can set a forced mode for public API through the request header "Forced-Mode" with values "real" or "paper".

Supported Leverage Types

Previously API supported custom value for leverage_type. Now it is DEPRECATED and needs to be changed to isolated. If you pass custom value as leverage[type] 3commas saves it as isolated anyway.

Supported leverage types depend on the market you use:

Market	Supported Leverage Types
FTX Futures	cross
Bybit	isolated, cross
Binance Futures COIN-M	isolated, cross
Bitmex	isolated, cross
Binance Futures	isolated, cross

Public API Endpoints

Deal status:

• CREATED
• BASE_ORDER_PLACED
• BOUGHT
• CANCEL_PENDING
• CANCELED
• COMPLETED
• FAILED
• PANIC_SELL_PENDING
• PANIC_SELL_ORDER_PLACED
• PANIC_SOLD

Permissions:

• BOTS_READ
• BOTS_WRITE
• ACCOUNTS_READ
• ACCOUNTS_WRITE
• SMART_TRADES_READ
• SMART_TRADES_WRITE

Rate limiters (rateLimitType)

• REQUESTS
• ORDERS

Rate limit intervals

• SECOND
• MINUTE
• DAY

Test connectivity to the Rest API (Permission: NONE, Security: NONE)

GET /ver1/ping

Weight: 1

Parameters: NONE

PongEntity

{
pong: string 
 } 

Test connectivity to the Rest API and get the current server time (Permission: NONE, Security: NONE)

GET /ver1/time

Weight: 1

Parameters: NONE

TimeEntity

{
server_time: integer 
 } 

Api credentials validity check (Permission: NONE, Security: SIGNED)

GET /ver1/validate

Weight: 1

Parameters: NONE

General Streams Information

• The base websocket endpoint is wss://ws.3commas.io/websocket
• Note that identifier is a JSON string

SmartTrades Streams

(Permission: SMART_TRADES_READ, Security: SIGNED)

• connect to the base websocket endpoint

• create valid signature:

    [linux]$ echo -n "/smart_trades" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= 8b30fb42a82e4dcfb4d0273d2910c7ae0add2b32938b19c27c44e306c56c20bc
  

• build identifier(ruby Hash for example)

    identifier = {
      channel: 'SmartTradesChannel',
      users: [
        {
          api_key: 'vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8Asma',
          signature: '8b30fb42a82e4dcfb4d0273d2910c7ae0add2b32938b19c27c44e306c56c20bc'
        }
      ],
    }

• build valid message for websocket protocol

    {
      "identifier": identifier.to_json,
      "command": "subscribe"
    }

• send message to subscribe stream

  • the message will look like this:

      {
        "identifier":"{
        \"channel\":\"SmartTradesChannel\",
        \"users\":
          [
            {\"api_key\":\"vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8Asma\",\"signature\":\"8b30fb42a82e4dcfb4d0273d2910c7ae0add2b32938b19c27c44e306c56c20bc\"}
          ]}",
        "command": "subscribe"
      }
    

• you will receive confirm_subscription message and then you will receive all of updates of users smart trades

Deals Streams

(Permission: BOTS_READ, Security: SIGNED)

• connect to the base websocket endpoint
• create valid signature:

    [linux]$ echo -n "/deals" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= 92cbefb3a2f2a8e94479470c7b5eb7cce43037947461c665e9b7f8b05a81a936
  

• build identifier(ruby Hash for example)

    identifier = {
      channel: 'DealsChannel',
      users: [
        {
          api_key: 'vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8Asma',
          signature: '92cbefb3a2f2a8e94479470c7b5eb7cce43037947461c665e9b7f8b05a81a936'
        }
      ],
    }

• build valid message for websocket protocol

    {
      "identifier": identifier.to_json,
      "command": "subscribe"
    }

• send message to subscribe stream
  • the message will look like this:

      {
        "identifier":"{
        \"channel\":\"DealsChannel\",
        \"users\":
          [
            {\"api_key\":\"vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8Asma\",\"signature\":\"92cbefb3a2f2a8e94479470c7b5eb7cce43037947461c665e9b7f8b05a81a936\"}
          ]}",
        "command": "subscribe"
      }
    

• you will receive confirm_subscription message and then you will receive all created or updated users deals

3commas-official-api-docs's Issues

Please delete this sorry

Please delete this sorry

SmartTrades - add status "partially_bought" or "partially_filled"

Hi guys
This is an issue I'm tracking for a long time to confirm it is on the 3c side or my code.
And after a lot of observations i can confirm this :
1 opened smart trade with a limit order, status condition is buy_order_placed.
Then after some time without being bought it is canceled. then we get this:

so, as you can see, all orders where CANCELED right ?
But NO!
The buy order was NOT canceled and the coin was bought in some time after this.
And you got THIS :

this is happening all the time and i just observed the same issue with more then 10 smarttrades in the last 24 h.

My current solution was to create a bot that will check all open smartrades, dca and grid and pointme out what assets are "left"and not used in any orders.

I called it 3ca-audit-letfovers

But the problem is that i need to manually deal with each of then, creating a manual smartrade, checking the bought price, etc,..

It seems that the problem is related to partial filled orders and there is no status for this on 3commas.

Can you pls add the status "partially_bought" or "partially_filled" for smartrades?

Is it possible to get bot list name

I have read document but it's limit only 100 records.
Is it possible to get all bot_name or bot_id.
thank you

"msg": "Other error occurred: record_invalid Invalid parameters."

Hello guys, i have a problem.
I use the smart trade v2 with bogdanteodoru/py3cw application and I got this error this error many times in the row but sometimes the order passes and I dont change the type of each values.

Someone can help me plz ?

id_account = int
pair = str
unit_value = float
entry = float
levarage = str
all target = float
stop = float
I want buy a coin with a specific price. I have a other payload with a buy market but this one in most important. Thx a lot

        error, data = p3cw.request(
            entity='smart_trades_v2',
            action='new',
            payload={
                "account_id": id_account,
                "pair": pair,
                "instant": "false",
                "position": {
                    "type": "buy",
                    "units": {
                        "value": unit_value
                    },
                    "order_type": "conditional",
                    "conditional": {
                        "price": {
                            "value": entry
                        },
                        "order_type": "market"
                    }
                },
                "leverage": {
                    "enabled": True,
                    "type": "custom",
                    "value": leverage
                },
                "take_profit": {
                    "enabled": "true",
                    "steps": [
                        {
                            "order_type": "limit",
                            "price": {
                                "value": targets[0],
                                "type": "bid"
                            },
                            "volume": 25
                        },
                        {
                            "order_type": "limit",
                            "price": {
                                "value": targets[1],
                                "type": "bid"
                            },
                            "volume": 25
                        },
                        {
                            "order_type": "limit",
                            "price": {
                                "value": targets[2],
                                "type": "bid"
                            },
                            "volume": 25
                        },
                        {
                            "order_type": "limit",
                            "price": {
                                "value": targets[3],
                                "type": "bid"
                            },
                            "volume": 25
                        }
                    ]
                },
                "stop_loss": {
                    "enabled": "true",
                    "order_type": "market",
                    "conditional": {
                        "price": {
                            "value": stop,
                            "type": "bid"
                        }
                    }
                }
            }
        )

Required Balance on Existing Grid Bot

I am trying to edit a grid bot and want to check the balances before I restart the bot. This error is always returned. With a running bot, or a stopped bot. This call only seems to work on a bot that has not been started.

{"error":"unprocessable_entity","error_description":"The bot cannot be started. The process of canceling previous orders is ongoing. Try later."}

https://github.com/3commas-io/3commas-official-api-docs/blob/master/grid_bots_api.md#get-required-balances-to-start-botpermission-bots_read-security-signed

add active_deals_usd_profit field in /bots endpoint

Currently the active_deals_usd_profit could be obtained from the /bots/stats endpoint. I think it is a good metric to add in the /bots response. It has almost all information anyway.
Right now, If I need to have that metric for all enabled bots, I would need to send a request for every single bot id to /bots/stats.

Fail to create Step Order

Getting the follow error.

{
  error: 'record_invalid',
  error_description: 'Invalid parameters',
  error_attributes: {
    'take_profit[steps]': [ 'is invalid' ],
    'take_profit[steps][0][price][type]': [ 'is missing' ],
    'value,percent': [ 'are missing, exactly one parameter must be provided' ]
  }
}

Input:

{
  "account_id": 1,
  "pair": "USDT_BNB",
  "position": {
    "type": "buy",
    "order_type": "limit",
    "units": {
      "value": 5
    },
    "price": {
      "value": 19.6
    }
  },
  "take_profit": {
    "enabled": true,
    "steps": [
      {
        "order_type": "limit",
        "price": {
          "value": 21,
          "type": "bid"
        },
        "volume": 100
      }
    ]
  },
  "stop_loss": {
    "enabled": false
  }
}

Error: max_active_deals must be less than or equal to 1

We're having issues updating our 3commas bots via API. We're getting the same error when using the REST API and the python wrapper. The API response we're getting is the following even though the bot type is Bot::MultiBot:

{
  "error": "record_invalid",
  "error_description": "Invalid parameters",
  "error_attributes": {
    "max_active_deals": [
      "must be less than or equal to 1"
    ]
  }
}

Here's the payload we're sending:

error, data = p3cw.request(
    entity='bots',
    action='update',
    action_id='::hidden::',
    payload={
        'min_price': None,
        'trailing_deviation': 0.2,
        'leverage_custom_value': None,
        'updated_at': '2020-07-14T05:41:35.533Z',
        'cooldown': '0',
        'trailing_enabled': False,
        'start_order_type': 'limit',
        'id': '::hidden::',
        'max_active_deals': 8,
        'deletable?': True,
        'min_volume_btc_24h': '0.0',
        'safety_order_step_percentage': 1.3,
        'active_deals_count': 0,
        'leverage_type': 'not_specified',
        'disable_after_deals_count': None,
        'strategy': 'long',
        'strategy_list': [{'strategy': 'keiko'}],
        'safety_order_volume_type': 'quote_currency',
        'active_safety_orders_count': 1,
        'type': 'Bot::MultiBot',
        'is_enabled': True,
        'take_profit_type': 'total',
        'finished_deals_profit_usd': '279.84257194',
        'account_id': "::hidden::",
        'deal_start_delay_seconds': None,
        'take_profit': 1.52,
        'tsl_enabled': False,
        'stop_loss_timeout_enabled': False,
        'finished_deals_count': '43',
        'active_deals': [
        ],
        'pairs': ['USDT_ADA'],
        'stop_loss_type': 'stop_loss',
        'name': 'bm1-17-keiko-recset-usdtall__updated__',
        'base_order_volume_type': 'quote_currency',
        'created_at': '2020-06-29T19:58:30.074Z',
        'safety_order_volume': 150,
        'account_name': 'bm1-keiko-busd-eth-usdt',
        'max_price': None,
        'profit_currency': 'quote_currency',
        'max_safety_orders': 3,
        'stop_loss_timeout_in_seconds': 0,
        'deals_counter': None,
        'stop_loss_percentage': '0.0',
        'martingale_volume_coefficient': 2,
        'easy_form_supported': False,
        'martingale_step_coefficient': 2.4,
        'base_order_volume': 50,
        'allowed_deals_on_same_pair': 1
    }
)

Could this be a bug in the API?

Any help would be greatly appreciated. Thanks!

/bots/stats?bot_id=<id> should return null instead of 0

In other case a misleading information is given.
Account: real
GET /bots/stats?bot_id=<some_id> returns something like this

{
    "overall_stats": {
        "BTC": "0.05083003"
    },
    "today_stats": {
        "BTC": "0.00364445"
    },
    "profits_in_usd": {
        "overall_usd_profit": 2922.1,
        "today_usd_profit": 209.51,
        "active_deals_usd_profit": -1848.31
    }
}

When we switch to the paper account and perform the same GET this response is returned:

{
    "overall_stats": {},
    "today_stats": {},
    "profits_in_usd": {
        "overall_usd_profit": 0.0,
        "today_usd_profit": 0.0,
        "active_deals_usd_profit": 0.0
    }
}

This gives misleading information. overall_usd_profit is stated a zero, which is a valid value for this field and should be interpreted that the is no profit. This is clearly not true.

A better approach would be to return null in that case. null is not equal to 0. 0 IS a value, null is absence of a value.

{
    "overall_stats": {},
    "today_stats": {},
    "profits_in_usd": {
        "overall_usd_profit": null,
        "today_usd_profit": null,
        "active_deals_usd_profit": null
    }
}

Edit bot API single parameter patch

Edit bot (Permission: BOTS_WRITE, Security: SIGNED)
PATCH /ver1/bots/{bot_id}/update

Hi,

I'm trying to update a single parameter in my bot (max_active_deals) based on when my balance changes but failing to do that.
Looks like I need to send all other parameters to patch a bot.

Is there a future plan to allow a single parameter bot patch or am I doing it wrong?

Thanks,
JZ

Ignoring paper orders

Seems that for whatever reason 3commas are ignoring paper orders.

"Hi, from the last 10 days 3c.exchange is ignoring totally all the paper orders, anybody else is having this issue ? Thanks."

bogdanteodoru/py3cw#5

method GET /ver1/accounts/currency_rates dos not return 'lotStep'

HI there at 3commas team.

Some times there is no 'lotStep' in the response.

Normal behavior :

{'last': '0.00000087', 'bid': '0.00000086', 'ask': '0.00000087', 'orderbook_ask': '0.00000087', 'orderbook_bid': '0.00000086', 'orderbook_last': '0.00000087', 'orderbook_price_currency': 'BTC', 'strategy_name': 'orderbook_price', 'contract_strategy_name': 'orderbook_price', 'minPrice': '0.00000001', 'maxPrice': '1000.0', 'priceStep': '0.00000001', 'minLotSize': '1.0', 'maxLotSize': '90000000.0', 'lotStep': '1.0', 'minTotal': '0.0001'}

sometimes no 'lotStep' : maybe is something missing for some markets.

{'last': 8.6e-07, 'bid': 8.6e-07, 'ask': 8.7e-07, 'orderbook_ask': 8.7e-07, 'orderbook_bid': 8.6e-07, 'orderbook_last': 8.6e-07, 'orderbook_price_currency': 'BTC', 'strategy_name': 'orderbook_price', 'contract_strategy_name': 'orderbook_price', 'minLotSize': '454.54545455', 'minTotal': '0.0005', 'priceStep': '0.00000001'}

TP percentage condition available only with TrailingBuy

When I place a SmartTrade Create, with TrailingBuyEnabled=false, and with TakeProfit and Stoploss enabled, it throws error:

{"error":"Wrong param(s)","error_description":"TP percentage condition available only with TrailingBuy"}

Isn't it possible to create a Smart Trade without TrailingBuy, and if I want TakeProfit and Stoploss?

It should be possible to access /bots/stats?bot_id=<bot_id> without checking the paper-state of the account

If this endpoint is accessed while being in a different account state (paper vs real) a empty response is sent.
{ "overall_stats": {}, "today_stats": {}, "profits_in_usd": { "overall_usd_profit": 0.0, "today_usd_profit": 0.0, "active_deals_usd_profit": 0.0 } }

This forces a additional check if the account is in the correct state and probably one more if the state is the wrong one.
This lead to three requests.
If I request a special bot_id I am sure I want the information about this bot. This request should be stateless.

Consider adding 'note' parameter to SmartTradesV2 API?

SmartTradesV2 API looks good!

However, I don't see a note parameter for "Create smart trade". Apparently, there is now a separate "Set note" endpoint for this purpose.

It would be nice to have note as an optional parameter, because it can be used to hold a token that enables the client (e.g., a trading app) to identify the order on the exchange.

The scenario is this: (1) a HTTPS connection is opened and "Create smart trade" is POSTed to the server (2) HTTPS connection fails, returning a timeout error to the client. At this point, the order has been processed by the exchange, but the client doesn't have confirmation, and the "Set note" endpoint doesn't help. The client must now query for all open orders and try to guess a match. This would be easier if the client could provide a unique token via the note parameter.

Thanks!

start_new_deal error with payload

Hi, i'm testing the start new deal action:
if i send a plain start new deal command it works ok
#start deal error, data = p3cw.request( entity='bots', action='start_new_deal', action_id='MYBOTID' ) data

but if i want to specify the pair with the payload i have an error

#start deal error, data = p3cw.request( entity='bots', action='start_new_deal', action_id='2120923', #payload={'pair':['USDT_XMR'],'skip_signal_checks':'True','skip_open_deals_checks':'True'} )
This is the error i have

{'error': True, 'msg': "Other error occurred: 'str' object has no attribute 'get'"}

This is the bot as is configured:

{'id': 2120923, 'account_id': MYACCOUNTIR, 'is_enabled': True, 'max_safety_orders': 0, 'active_safety_orders_count': 0, 'pairs': ['USDT_XMR'], 'strategy_list': [{'options': {}, 'strategy': 'manual'}], 'max_active_deals': 1, 'active_deals_count': 1, 'deletable?': False, 'created_at': '2020-12-16T16:15:56.210Z', 'updated_at': '2020-12-16T16:32:39.367Z', 'trailing_enabled': False, 'tsl_enabled': False, 'deal_start_delay_seconds': None, 'stop_loss_timeout_enabled': False, 'stop_loss_timeout_in_seconds': 0, 'disable_after_deals_count': None, 'deals_counter': None, 'allowed_deals_on_same_pair': None, 'easy_form_supported': False, 'name': 'Test Bot', 'take_profit': '5.0', 'base_order_volume': '10.0', 'safety_order_volume': '10.0', 'safety_order_step_percentage': '1.0', 'take_profit_type': 'total', 'type': 'Bot::SingleBot', 'martingale_volume_coefficient': '1.0', 'martingale_step_coefficient': '1.0', 'stop_loss_percentage': '0.0', 'cooldown': '0', 'strategy': 'long', 'min_volume_btc_24h': '0.0', 'profit_currency': 'quote_currency', 'min_price': None, 'max_price': None, 'stop_loss_type': 'stop_loss', 'safety_order_volume_type': 'quote_currency', 'base_order_volume_type': 'quote_currency', 'account_name': 'Paper Account 210260', 'trailing_deviation': '0.2', 'finished_deals_profit_usd': '0', 'finished_deals_count': '0', 'leverage_type': 'not_specified', 'leverage_custom_value': None, 'start_order_type': 'limit', 'active_deals': [{'id': 236744748, 'type': 'Deal', 'bot_id': 2120923, 'max_safety_orders': 0, 'deal_has_error': False, 'from_currency_id': 0, 'to_currency_id': 0, 'account_id': 29062281, 'active_safety_orders_count': 0, 'created_at': '2020-12-16T16:34:16.914Z', 'updated_at': '2020-12-16T16:34:17.336Z', 'closed_at': None, 'finished?': False, 'current_active_safety_orders_count': 0, 'current_active_safety_orders': 0, 'completed_safety_orders_count': 0, 'completed_manual_safety_orders_count': 0, 'cancellable?': True, 'panic_sellable?': True, 'trailing_enabled': False, 'tsl_enabled': False, 'stop_loss_timeout_enabled': False, 'stop_loss_timeout_in_seconds': 0, 'active_manual_safety_orders': 0, 'pair': 'USDT_XMR', 'status': 'bought', 'take_profit': '5.0', 'base_order_volume': '10.0', 'safety_order_volume': '10.0', 'safety_order_step_percentage': '1.0', 'bought_amount': '0.06554', 'bought_volume': '10.1111258248', 'bought_average_price': '154.27412', 'sold_amount': '0.0', 'sold_volume': '0.0', 'sold_average_price': '0', 'take_profit_type': 'total', 'final_profit': '-0.02347577', 'martingale_coefficient': '1.0', 'martingale_volume_coefficient': '1.0', 'martingale_step_coefficient': '1.0', 'stop_loss_percentage': '0.0', 'error_message': None, 'profit_currency': 'quote_currency', 'stop_loss_type': 'stop_loss', 'safety_order_volume_type': 'quote_currency', 'base_order_volume_type': 'quote_currency', 'from_currency': 'USDT', 'to_currency': 'XMR', 'current_price': '154.09', 'take_profit_price': '162.15', 'stop_loss_price': None, 'final_profit_percentage': '0', 'actual_profit_percentage': '-0.12', 'bot_name': 'Test Bot', 'account_name': '', 'usd_final_profit': '-0.02', 'actual_profit': '-0.0221662834', 'actual_usd_profit': '-0.0221662834', 'failed_message': None, 'reserved_base_coin': '10.1111258248', 'reserved_second_coin': '0.06554', 'trailing_deviation': '0.2', 'trailing_max_price': None, 'tsl_max_price': None, 'strategy': 'long'}]}

Swagger doc out of date

The swagger doc is out of date (missing smart trade V2) so I don't know what to expect in the response.

Create smart trade example doesn't work

The create smart trade example in the documentation does no longer work. Fix it.

/accounts Transfer History undocumented required parameter

The parameters listed below are missing off a required parameter "size".
I have tried size Int and size string with "100", 100, but none work.
What is the size parameter?
Error:

"error_description": "{\"code\"=>-1102, \"msg\"=>\"Mandatory parameter 'size' was not sent, was empty/null, or malformed.\"}",
          "error": "unknown_market_api_error"

Don't emit null values

3Commas validation fails when null values are emitted for unused parameters. Change JsonSerializer settings to ignore null values.

/ver1/users/change_mode change mode also in GUI on the website

When I work on API and e.g. automatically downloading data, the mode gets switched in background. When I switch in GUI API gets also affected. Can you please get rid of this dependency? It is anoying and also dangerous when I quickly need to do some changes or deal operations and scripted API access switch me over to paper multiple times when I quickly need to close deal.

add parameters to get history for smartrades, grids, dca, or any endpoint with history

Hello guys at 3commas team.
I'm working on a automated retrieval process for historic data from my bots and I just noted that all the endpoints to get historical data does not have a parameter to inform FROM date.
So, my request here is to add a parameter FROM Date or if you want to be compliant with the most APIs out there something like will be nice and certainly will save 3commas resources serving the API request.

Name	Type	Mandatory	Description
startTime	LONG	NO	Default: 90 days from current timestamp
endTime	LONG	NO	Default: present timestamp
offest	INT	NO	default:0
limit	INT	NO

Grid strange behavior

Hi guys at 3commas team
I just noted this behavior in some of my Grid bots.

as you can see there is scrambled orders, buy and sell mixed on what i can observe as a wrong lines.
Is this a problem with the grid algorithm ?
Is there a limit for the number of lines stored in the Grid structure ? - I noted that all lines are stored, even the canceled ones and as I'm running the same Grid for long time it should has tons of lines. Is this a problem ? is there a solution or a workaround to fix it ?

The way I'm solving this for now is to edit and restart the bot.

thanks!

Close dela at market price missing endpoint?

HI, i haven't found the proper way to close a deal trough the API, from the tv signals i can invoke close_at_market_price.
Can't find the equivalent in the deals API, only panic sell.

Average for smart trade v2 does not work properly

When I send following payload :

{
id : 123456,
order_type: "market",
units: { value: 30}
}

It returns following error

{ error: 'record_invalid',
error_description: 'Invalid parameters',
error_attributes:
{ units: [ 'is invalid' ],
'units[value]': [ 'is missing', 'is invalid' ] } }

Thank you for your assistance.

convert dust endpoint

Hi there at 3commas

Will be very practical to have the endpoint to convert dust to BNB for binance and of course for 3c.exchange, as it already exist as an enpoint ion the Binance API.

https://binance-docs.github.io/apidocs/spot/en/#dust-transfer-user_data

Error take_profit[steps][price][type] missing

I'm trying to place an order using the /public/api/v2/smart_trades endpoint with the following parameters:

Array
(
    [account_id] => 99999
    [pair] => USDT_ADADOWN
    [position] => Array
        (
            [type] => buy
            [order_type] => market
            [units] => Array
                (
                    [value] => 50
                )

        )

    [take_profit] => Array
        (
            [enabled] => 1
            [steps] => Array
                (
                    [0] => Array
                        (
                            [order_type] => market
                            [price] => Array
                                (
                                    [value] => 0.477
                                    [type] => last
                                )

                            [volume] => 50
                        )

                    [1] => Array
                        (
                            [order_type] => market
                            [price] => Array
                                (
                                    [value] => 0.485
                                    [type] => last
                                )

                            [volume] => 50
                        )

                )

        )

)

The request results in the following error response:

{"error":"record_invalid","error_description":"Invalid parameters","error_attributes":{"take_profit[steps]":["is invalid"],"take_profit[steps][price][type]":["is missing"],"value,percent":["are missing, exactly one parameter must be provided"]}}

However, as you can see above, take_profit[steps][price][type] is actually set. When I set take_profit[enabled] to false it works but of course the take profit isn't being applied.
Is this a bug or am I doing something wrong?

New Feature Request: Yesterday's Profit

Hi,

Would it be possible to add a 'yesterdays profit' to the bot API?

I notice this is missing from your app too, and it's a feature I use every day but have to go through the web interface.

Thanks!

Keep getting 429 return

I've used the same app for a few weeks and never had any issues with a 429 response. All of a sudden, I keep receiving "too many requests" return even the first request.

Deposit address

Hello guys at 3commas Team.

Will be really nice to have an endpoint do fetch the deposit address like

GET /ver1/accounts/{account_id}/depositAddress

https://github.com/binance-exchange/binance-official-api-docs/blob/ce20ed2482b6e9ffdd2e43a72a24fbaaf658787b/wapi-api.md

add funds to active smart trades

How to add funds to an active smart trade?

deals/{deal_id}/show returns empty account_name

The field "account_name" is always empty.
I know I can get the account name using the deal's account id by another method, but I think this needs to be fixed.

Endpoint: /ver1/deals/{deal_id}/show

Postman result:

GET /ver1/smart_trades does not work properly

Hi Team,

It was working fine there are a couple of month but I noticed it does not work anymore especially when api is called with {scope: 'active'} parameter.
Any breaking change somewhere?

Thank you.

quantity_per_grid not taking values in decimal

If the value of 'quantity_per_grid' in https://github.com/3commas-io/3commas-official-api-docs/blob/master/grid_bots_api.md#create-grid-bot-permission-bots_write-security-signed is a decimal the following error comes

{'error': True, 'msg': "Other error occurred: 'str' object has no attribute 'get'"}

But, if it's value is rounded to an integer and sent then no error comes, it works perfectly fine.

The entire payload -

{'account_id': xxxxx, 'pair': 'USDT_XLM', 'upper_price': 1.864588075, 'lower_price': 1.118752845, 'quantity_per_grid': 6.637518383, 'grids_quantity': 100.0, 'leverage_type': 'custom', 'leverage_custom_value': 20.0, 'is_enabled': False}

noob how-to for Google Sheets

Hi Guru's

Where could I find a more noob-friendly description of using this API to pull data to Google Sheets?
How can I sign the message?
In fact, I even fail to do it in Postman.

Creating a bot returns error for strategy list

I cannot create a bot from the python wrapper.

I created this issue: bogdanteodoru/py3cw#3
And a few days before, someone else created a similar issue: bogdanteodoru/py3cw#1

The other two APIs do not have any posted issues for this problem.

The issue is in how the strategy list is formatted. I believe the problem is either the endpoint is structured differently than documented, or something special needs to be done for the formatting of the request that is different than how the requests package usually formats payloads.

Would it be possible to get an example request that successfully creates a bot to verify the endpoint? I think I can work back from that to figure out how the payload should be formatted within the Python wrapper to create a bot.

transfer_data not returning all accounts data

I added two exchange accounts but calling transfer_data only returning one exchange account.

SmartTrade Version2 Metadata Missing from 3commas_swaggerdoc.json

The data structure that is returned from GET /v2/smart_trades is quite different than v1.

Is there any way to get an updated swaggerdoc.json file with metadata? Thanks!

Grid bots list - [bug] inconsistent parameters

Hi guys at 3commas team.
I just went to a bug on the grid bots list endpoint.

Name	Type	Mandatory	Values(default)	Description
account_ids	array[integer]	NO		Filter by account id
account_types	array[string]	NO		Filter by account type
state	string	NO	enabled, disabled	Filter by bot state
sort_by	string	NO	current_profit, bot_id, pair	Sort column
sort_direction	string	NO	desc, asc	Sort direction
limit	integer	NO	(10)
offset	integer	NO	(0)

check this out when you do not inform nothing in the payload you get only 10 bots.
if you inform the limit like 1000 without ANY other parameter, then you get all bots.
If you inform the limit and the account id, you get again only 10 bots.
can you pls check on that?

`payload = {}

len(bots)
10

payload = {'limit': 1000}

len(bots)
11

payload = {'limit': 1000, 'account_ids': 993456789}
len(bots)
10
`

tkx!

Error units_to_buy: Should change with step 0.01

Getting the following error when doing an API call to /ver1/smart_trades/create_smart_trade when having units_to_buy set to a float with a precision > 2:

{"error":"record_invalid","error_description":"Invalid parameters","error_attributes":{"units_to_buy":["Should change with step 0.01"]}}

Now, this doesn't really make sense, since with the current BTC price 0.01 BTC would be $300, which is way higher than the minimum trade of $10.
Like this it's impossible to trade low amounts of high valued coins.

unknown_market50x_error

Hi,

Sometimes I get error:
{"error_description":"Network error occurred. HTTP code: 502","error":"unknown_market50x_error"}

When executin API query: /public/api/ver1/deals/437364155/data_for_adding_funds

What does it mean?

Thanks,

Ignacio

Audio/btc binance grid bot errors

Dear user,Thanks for your reply.With regard to your problem, the minimum order size of the trading pair Audio/BTC is 1, which means the minimum buy/sell order is 1 Audio, please kindly set the quantity is 1 or more than 1 and try again.​If the problem persists, please provide us the order details so that we can help you better.Thanks again for your waiting and understanding, if you have any questions in the future, please do come back to us, we will try our best to help you.At last, we hope you have a good journey in Binance.
Best Regards,
Binance Support Team | Dear user,Thanks for your reply.With regard to your problem, the minimum order size of the trading pair Audio/BTC is 1, which means the minimum buy/sell order is 1 Audio, please kindly set the quantity is 1 or more than 1 and try again.​If the problem persists, please provide us the order details so that we can help you better.Thanks again for your waiting and understanding, if you have any questions in the future, please do come back to us, we will try our best to help you.At last, we hope you have a good journey in Binance.
Best Regards,
Binance Support Team

Switching to paper trading account in the UI also switches API over

The accounts etc. returned by the API depend on whether you selected the paper trading account in the web UI or not.

This seems dangerous as a single click in the UI can make all your API calls to go to the wrong accounts resp. fail

There's also no good way to test the API on paper trading while having a real setup running at the same time.

Generate a valid signature

Hello, sorry if this is not allowed to post here.
I'm trying to connect 3commas api, but keep getting "signature_invalid" message.
When I try to produce hmac sha256 signature, I can get the correct result use the same parameters in docs example, but I can't get my own secret key to work.

Here is what I do:

headers = {
    'APIKEY': 'XXX'
}

params=b'/public/api/ver1/deals'
secret = b'YYY'
signature = hmac.new( secret , params, hashlib.sha256).hexdigest()
query = "signature={}".format(signature)


resp = requests.request('GET',
                        'https://3commas.io' + params + "?" + query,
                        headers=headers)

reqsjson = json.loads(resp.text)
print(json.dumps(reqsjson, indent=4, sort_keys=True))

The error I get:

{
    "error": "signature_invalid", 
    "error_description": "Provided signature is invalid"
}

Any help would be much appreciated.

deals/add_funds not adding the right currency

When executing this in a BTC/USDT pair bot:

deals/$deal_id/add_funds?deal_id=$deal_id&quantity=20&is_market=true

It returns:

{"error_description":"Insufficient funds","error":"not_enough_money"}

But in the Bot log I see that it tried to buy BTC instead of USDT:

In the deals data (GET /ver1/deals/{deal_id}/data_for_adding_funds) it says that the "adding_funds_currency" is USDT:

{"orderbook_price":"56711.15","price_per_one_unit_strategy_name":"orderbook_price","account_id":29199035,"quote_currency":"USDT","base_currency":"BTC","adding_funds_currency":"USDT","available_amount":"14649.61200751","limits":{"minPrice":"0.01","maxPrice":"200166.15","priceStep":"0.01","minLotSize":"0.000001","maxLotSize":"9000.0","lotStep":"0.000001","minTotal":"10.0","maxMarketBuyAmount":"100.10172496","maxMarketSellAmount":"100.10172496","marketBuyMinTotal":"10.0"},"market_supported":true,"is_contract":false,"take_profit_price":"200166.15","stop_loss_price":null,"account_type":"Account::PaperTradingAccount","deal_type":"long","pair":"USDT_BTC","limit":"10.00000000","market_buy_min_total":"10.0","min_lot_size":"0.00000100","leverage_custom_value":null}

GridBotProfitsEntity Date Format

The GridBotProfitsEntity is adding "UTC" to the end of the "created_at" data when it returns. This is throwing off the default json Serializer. This doesn't seem to happen with other dates. The documentation says the format is supposed to be ""2018-08-08 08:08:08", but it isn't. I can make a workaround, but wondered if the 3Commas team might want to see if this is a bug or if they intend to send UTC back in the string. Fine with me either way.

account_table_data on_orders update timeframe

Hej guys
I'm using this endpoint to watch for leftovers that remains for some reason without any orders attached, and after some time I noted that the field "on_orders" is not accurately updated.
I'm using it mostly on Binance and 3c.exchange.

Can you pls check on that or reply about the update timeframe for that respective field?

tkx.

Does this API work for 3c.Exchange as well?

Does this api work for 3c.exchange as well?

extend accounts/currency_rates with maxleverage value

For margin/future accounts, it would be handy to have a value displaying the max leverage.
According to https://www.binance.com/en/support/articles/360033162192 this is dependent on the pair.
Some have max 25x, others 25x of 75x. BTC has max of 125x

smarttrading V2 missing buy steps

In smarttrading V1 refreshsmarttrade result returns buy_steps as array with internal id (to cancel).
In V2, only a node "position" is returned, but no list of buy_steps.

It could be a quick win to take over the buy_steps of V1 to V2.
This way buy_steps can be cancelled in V2, which was possible in V1