Introduction

Welcome to Coinlocally Partnership API documents.
If you are here, then you have successfully gain access license to work with our Partnership APIs. Congratulations!

The full description of the APIs are in the middle and how to request them is provided in the right part along with the expected result of each one. We have tried to explain as clearly as possible. However, if you encounter problems requesting APIs or the result was not what you expected, you can contact our support.

Changelogs

2023-07-30 - Refactor partner APIs and rewrite documents.
2022-03-05 - Add version 1.0.0 of API documents.

General Information

API Information

The base endpoint is: https://api.coinlocally.com
All endpoints return either a JSON object or array available in the result key.
All time and timestamp related fields are in unix timebased (milliseconds).
Your signed request is only available for 20 secconds. read Signing Data section for more information.

Authentication

curl "{API Endpoint}"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

Coinlocally Partnership APIs uses Key and Secret pair to allow partners access to the APIs.
You can manage your credential pairs at API Key Dashboard.

With this approach, critical data is signed with your secret and no one can not manipulate it (Man-in-the-middle attack).

Protect your credential Key and Secret. If they are leaked, be sure to replace them.

For any request call you must first sign your prepared data with your Secret. Then, pass your Key and Signature to that HTTP request header. Check out following table for correct header names.

HTTP Header Names

Header	Mandatory	Description
x-key	True	Your credential API Key.
x-signature	True	The Signature created by your secret.

Signing Data

As you know already, you must sign your request data. You must sign data based on endpoint's HTTP verb, for GET endpoints sign request's query and for POST,PUT,DELETE sign request's body.
Remember to add timestamp parameter to your body or query in milliseconds (based on your endpoint as explained) as well.

Please use HMAC-SHA256 algorithm to sign your data with your given SIGNATURE

Information

Get Partnership Account Information

curl -X GET "https://api.coinlocally.com/api/v1/partners/information"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

{
   error: false,
   code: 0,
   result: {
      maxSubAccounts: 100,
      totalSubAccounts: 54,
      isActive: true
   }
}

Genral information about your partnership account.

HTTP Request

GET /api/v1/partners/information

Response Parameters

Parameter	Type	Optional	Description
maxSubAccounts	Number	False	Maximum sub accounts you allowed to create.
totalSubAccounts	Number	False	Total sub accounts you already created.
isActive	Boolean	False	Show whether your partnership account is active or not.

Sub Accounts

Create New Sub Account

curl -X POST "https://api.coinlocally.com/api/v1/partners/sub-accounts"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

   -d "email"="[email protected]"
   -d "tag=myUserTag"
   -d "timestamp=1646411759765"

{
   error: false,
   code: 0,
   message: "Sub account created successfully."
   result: {
      subAccountId: 24,
      email: "[email protected]"
      tag: "myUserTag",
   }
}

This request will generate a sub account under your pertnership master account that is also a real Bybit account.

HTTP Request

POST /api/v1/partners/sub-accounts

Body Parameters

Parameter	Type	Mandatory	Description
email	String	True	An email for your sub account.
tag	String	True	Tag name for your sub account.
timestamp	Number	True	The timestamp you made request in milliseconds.

The tag parameter may help in your business logic somehow.

Response Parameters

Parameter	Type	Optional	Description
subAccountId	Number	False	Your new sub account ID.
email	String	False	Your new sub account email.
tag	String	False	Your new sub account tag name.

Get Sub Accounts List

curl -X GET "https://api.coinlocally.com/api/v1/partners/sub-accounts?limit=2&page=1"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

{
   error: false,
   code: 0,
   result: [{
      subAccountId: 24,
      email: "[email protected]"
      tag: "staoshi",
      createdAt: 1690785274333
   }, {
      subAccountId: 25,
      tag: "sbz",
      email: "[email protected]"
      createdAt: 1690796316825
   }],
   currentPage: 1,
   totalPages: 13
}

List of sub accounts you created.

HTTP Request

GET /api/v1/partners/sub-accounts

Query Parameters

Parameter	Type	Mandatory	Description
subAccountId	Number	False	Optional sub account ID filter.
tag	String	False	Optional tag name filter.
limit	Number	Optional limit for page pagination.
page	Number	Optional page number for page pagination.
timestamp	Number	True	The timestamp you made request in milliseconds.

Response Parameters

Parameter	Type	Optional	Description
subAccountId	Number	False	Sub account ID.
tag	String	False	Sub account tag name.
email	String	False	Sub account email address.
createdAt	String	False	Sub account create date.

Sub Account Credentials

Create New Credential

curl -X POST "https://api.coinlocally.com/api/v1/partners/sub-accounts/credentials"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

   -d "subAccountId=24"
   -d "name=satoshikey"

{
   error: false,
   code: 0,
    message: "Your personal credential key for requested sub account pair has been created successfully.",
   result: {
      id: 67,
      key: "1qkYEMsPq1Vkos93oCQ10E",
      secret: "M1lftKwCsYeSOf5kADC03OavM01NlyesBp50"
   }
}

This API will generate a new credential (Key and Secret) pair for the requested sub account.
You can modify it's permissions later. These credential pairs are the way to communicate with the Bybit and Coinlocally APIs.

It is your responsibility to store, maintain and secure client credentials (Key and Secret) as they are real Bybit accounts that can be used for trading ans other things. You can't retrieve credentials Secret again.

HTTP Request

POST /api/v1/partners/sub-accounts/credentials

Body Parameters

Parameter	Type	Mandatory	Description
subAccountId	Number	True	Your sub account ID.
name	String	False	Optional name for sub account credential.
timestamp	Number	True	The timestamp you made request in milliseconds.

Response Parameters

Parameter	Type	Optional	Description
id	Number	False	Sub account new API credential ID.
key	String	False	Sub account new API Key.
secret	String	False	Sub account new API Secret.

Delete Credential

curl -X DELETE "https://api.coinlocally.com/api/v1/partners/sub-accounts/credentials"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

   -d "subAccountId=24"
   -d "credentialId=67" # Optional

{
   error: false,
   code: 0,
    message: "Your sub account credential(s) key pair has been deleted successfully.",
}

Delete one or all specific sub account credentials. If credentialId provided, that specific credential for requested sub account will be deleted, If not, all credentials will be deleted.

HTTP Request

DELETE /api/v1/partners/sub-accounts/credentials

Body Parameters

Parameter	Type	Mandatory	Description
subAccountId	Number	True	Your sub account ID.
credentialId	Number	False	Optional credential ID for deleting that specific credential.
timestamp	Number	True	The timestamp you made request in milliseconds.

Set Credential Permissions

curl -X PUT "https://api.coinlocally.com/api/v1/partners/sub-accounts/credentials"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

   -d "subAccountId=24"
   -d "name=satoshi" # Optional
   -d "spotEnabled=true" # Optional
   -d "futuresEnabled=true" # Optional
   -d "withdrawEnabled=false" # Optional
   -d "ipRestricted=true" # Optional
   -d "allowedIpAddresses=192.168.4.5,45.23.12.99" # Optional
   -d "timestamp=1646411759765"

{
   error: false,
   code: 0,
    message: "Your changes has been applied to your sub account credential key pair successfully.",
}

Set sub account ceredential new permissions.

HTTP Request

PUT /api/v1/partners/sub-accounts/credentials

Body Parameters

Parameter	Type	Mandatory	Description
subAccountId	Number	True	Your sub account ID.
name	String	False	Credential optional name.
spotEnabled	Boolean	False	Sub account credential spot trade permission.
futuresEnabled	Boolean	False	Sub account credential futures trade permission.
withdrawEnabled	Boolean	False	Sub account credential withdraw permission.
ipRestrcited	Boolean	False	Sub account IP restrcited permission.
allowedIpAddresses	String	False	Sub account allowed IP addresses seperated by comma.
timestamp	Number	True	The timestamp you made request in milliseconds.

You must enable ipRestrcited for sub account to restrcition works for defined allowedIpAddresses.

Get Credentials List

curl -X GET "https://api.coinlocally.com/api/v1/partners/sub-accounts/credentials?limit=2&page=1"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

{
   error: false,
   code: 0,
    result: [{
      id: 45,
      name: "satoshikey",
      key: "1qkYEMsPq1Vkos93oCQ10E",
      allowedIpAddresses: null,
      spotEnabled: true,
      futuresEnabled: true,
      withdrawEnabled: false,
      ipRestricted: false,
      createdAt: 1690785303335,
    }, {
      id: 48,
      name: null,
      key: "2sLTwMOsq9wlikIr9C3212",
      allowedIpAddresses: "192.168.4.2,67.23.92.12",
      spotEnabled: true,
      futuresEnabled: false,
      withdrawEnabled: false,
      ipRestricted: true,
      createdAt: 16907853136435,
    }],
   currentPage: 1,
   totalPages: 13
}

Sub accounts credentials list.

HTTP Request

GET /api/v1/partners/sub-accounts/credentials

Query Parameters

Parameter	Type	Mandatory	Description
subAccountId	Number	False	Optional sub account ID for filter.
limit	Number	False	Optional limit for page pagination.
page	Number	False	Optional page number for page pagination.
timestamp	Number	True	The timestamp you made request in milliseconds.

Response Parameters

Parameter	Type	Optional	Description
id	Number	False	Credential ID.
name	String	True	Credential name if set.
key	String	False	Credential API key.
allowedIpAddresses	String	True	Allowed IP addresses if set seperated by comma.
spotEnabled	Boolean	False	Shows whether spot trade is available or not.
futuresEnabled	Boolean	False	Shows whether futures trade is available or not.
withdrawEnabled	Boolean	False	Shows whether withdraw is available or not.
ipRestricted	Boolean	False	Shows whether IP restrcited policy is available or not.
createdAt	Number	False	Credential creation UNIX based timstamp in milliseconds.

Transfers

Spot Transfer

curl -X POST "https://api.coinlocally.com/api/v1/partners/transfers/spot"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

   -d "fromSubAccountId=24"
   -d "toSubAccountId=69"
   -d "asset=BTC"
   -d "amount=0.085"
   -d "timestamp=1646411759765"

{
   error: false,
   code: 0,
   message: "Asset transfered to destination successfully.",
   result: {
         asset: "BTC",
         fromSubAccountId: "24",
         toSubAccountId: "69",
         amount: "0.085",
         transferId: "r5ug9dzokze2z9i2",
         createdAt: 1644412643938
   }
}

Transfer asset between spot sub accounts or your partnership master spot account.

HTTP Request

POST /api/v1/partners/transfers/spot

Body Parameters

Parameter	Type	Mandatory	Description
fromSubAccountId	Number	False	Source sub account ID.
toSubAccountId	Number	False	Destination client ID.
asset	String	False	Asset to transfer.
amount	Number	False	Amount to transfer.
timestamp	Number	True	The timestamp you made request in milliseconds.

If you dont send fromSubAccountId asset will be transfer from your partnership master account.

If you dont send toSubAccountId asset will be transfer to your partnership master account.

Response Parameters

Parameter	Type	Optional	Description
asset	String	False	Asset transfered.
fromSubAccountId	Number	False	Source sub account ID. (on null for master account)
toSubAccountId	Number	False	Destination client ID. (on null for master account)
amount	String	False	Amount to transfered.
transferId	String	False	Internal transfer Tx ID.
createdAt	String	False	Transfer UNIX based timstamp in milliseconds.

The transferId is a unique transfer ID associated to the transfer you made.

Spot Transfers History

curl -X GET "https://api.coinlocally.com/api/v1/partners/transfers/spot?fromSubAccountId=24&limit=100&page=2&timestamp=1646411759765"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

{
   error: false,
   code: 0,
   result: [{
         asset: "BTC",
         amount: "0.085",
         fromSubAccountId: "24",
         toSubAccountId: "69",
         transferId: "r5ug9dzokze2z9i2",
         createdAt: 1644412643938
      }, {
         asset: "ETH",
         amount: "2.1712",
         fromSubAccountId: "24",
         toSubAccountId: null,
         transferId: "AddI8DoPl912eOhf",
         createdAt: 1644412645241,
   }],
   currentPage: 1,
   totalPages: 3
}

History of transfers you made. You may want to use filter options below to get better result from what you are looking for.

HTTP Request

GET /api/v1/partners/transfers/spot

Query Parameters

Parameter	Type	Mandatory	Description
fromSubAccountId	Number	False	Source sub account ID.
toSubAccountId	Number	False	Destination sub account ID.
asset	String	False	Asset name.
transferId	String	False	Transfer ID.
startDate	Number	False	History start date in UNIX based timstamp in milliseconds.
endDate	Number	False	History end date in UNIX based timstamp in milliseconds.
limit	Number	False	Optional limit for page pagination.
page	Number	False	Optional page number for page pagination.
timestamp	Number	True	The timestamp you made request in milliseconds.

Response Parameters

Parameter	Type	Optional	Description
asset	String	False	Asset name.
amount	String	False	The amount of asset.
fromSubAccountId	String	False	Sourde sub account ID.
toSubAccountId	String	False	Destination sub account ID.
transferId	String	False	Transfer ID.
createdAt	Number	False	Transfer create date in UNIX based timstamp in milliseconds.

toSubAccountId with value of null means that asset transfered to your partnership master account.

fromSubAccountId with value of null means that asset transfered from your partnership master account.

Deposits

Client Deposits History

curl -X GET "https://api.coinlocally.com/api/v1/partners/deposits?limit=1&page=1&timestamp=1646411759765"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

{
   error: false,
   code: 0,
   result: [{
      asset: "BTC";
      network: "BTC";
      subAccountId: 24;
      fromAddress: "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";
      toAddress: "1JvXhnHCi6XqcanvrZJ5s2Qiv4tsmm2UMy";
      toMemo: null;
      amount: "0.001241";
      txId: "79a7345b9323d395c40da54ac4a1fff9329cde8310cbc33987dbde2c96e02f97";
      status: "CONFIRMED";
      createdAt: 1644412645241;
      updatedAt: 1644212925474;
   }],
   currentPage: 1,
   totalPages: 1
}

Get all deposits history of your sub accounts. just like transfers history you can use filter options below as well.

HTTP Request

GET /api/v1/partners/deposits

Query Parameters

Parameter	Type	Mandatory	Description
subAccountId	Number	False	Your client ID.
asset	String	False	Asset name.
network	String	False	Network name.
startDate	Number	False	History start date in UNIX based timstamp in milliseconds.
endDate	Number	False	History end date in UNIX based timstamp in milliseconds.
limit	Number	False	Optional limit for page pagination.
page	Number	False	Optional page number for page pagination.
timestamp	Number	True	The timestamp you made request in milliseconds.

Response Parameters

Parameter	Type	Optional	Description
asset	String	True	Asset name.
network	String	True	Network name.
subAccountId	Number	True	Your sub account ID.
fromAddress	String	True	The Address that asset deposits from.
toAddress	String	True	The Address that asset deposits to.
toMemo	String	True	The memo (tag) of transaction.
amount	String	True	The amount of asset that deposits.
txId	String	True	The Tx ID (transaction ID) on associated network.
status	String	True	The current status of transaction.
createdAt	Number	True	Transaction start date in UNIX based timstamp in milliseconds.
updatedAt	Number	True	Transaction updated status date in UNIX based timstamp in milliseconds.

toMemo is set to null if sender did not set it or the network does not support memo (tag) feature.

status is a enum of PENDING and CONFIRMED that specified current transaction status on that network.

Withdraws

Submit Withdraw Request

curl -X POST "https://api.coinlocally.com/api/v1/withdraws"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

   -d "asset=USDT"
   -d "network=TRX"
   -d "address=TJanqYoB54BNV5QTh4UshNrCNzrvaBPiK4"
   -d "amount=12.76"
   -d "timestamp=1646411759765"

{
   error: false,
   code: 0,
   message: "Your withdraw request has been submitted successfully.",
}

Withdraw request is blocked for your sub account clients, even with their Bybit API Key and Secret they can't make a withdraw request call, unless you enable withdrawEnabled for that. Thus a best practice to accomplish withdraw for your clients is to first transfer their asset to your partnership master account and then submit a new withdraw request.

HTTP Request

POST /api/v1/withdraws

Body Parameters

Parameter	Type	Mandatory	Description
asset	String	True	Asset you want to withdraw.
network	String	True	Network name.
address	String	True	The destination address.
memo	String	False	Memo (tag) for this transaction.
internalFeeAction	String	False	Specifies how the fee for internal withdraw will work.
amount	String	True	The amount of asset you want to withdraw.
timestamp	Number	True	The timestamp you made request in milliseconds.

memo is an optional thing, sometimes known as tag. it may be required for some wallets.

The clientTxId is a unique transfer ID associated to the transfer you made.

If your destination wallet address was an internal wallet (in coinlocally), you can set internalFeeAction to TRANSFER_TO_DESTINATION for returning the fee to the destination account or TRANSFER_TO_DEPURTURE for returning the fee back to the departure account.

Withdraws History

curl -X GET "https://api.coinlocally.com/api/v1/withdraws?limit=2&timestamp=1646411759765"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

{
   error: false,
   code: 0,
   result: [{
      asset: "BTC",
      network: "BTC",
      amount: "1.34"
      priceInBtc: "1.34",
      priceInUsdt: "54334.32",
      address: "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
      memo: null
      fee: "0.00023",
      txId: "7d49bad64b3efcc956de0ea2d4c7da96e1a633b5f86ee760a09f9e2f633465ab",
      binanceId: "4fa33ea8e71b4a4433d507237e5a551b",
      internalFeeAction: null,
      status: "PENDING",
      reason: null
      createdAt: 1646411759765,
      updatedAt: 1646411767001,
   }, {
      asset: "USDT",
      network: "ETH",
      amount: "65.34"
      priceInBtc: "8.34",
      priceInUsdt: "102334.11",
      address: "0x84c57ac9448b9fd931d2b4803716aa4e76c8e82a",
      memo: null
      fee: "0.00113",
      txId: "0x4ccd206a5599cbf933095e40d2a9549ec36537315533928da77b9f830bc761d3",
      binanceId: "7213fea8e94b4a5593d507237e5a555b",
      internalFeeAction: "TRANSFER_TO_DESTINATION",
      status: "CONFIRMED",
      reason: null
      createdAt: 1646411789765,
      updatedAt: 1646411777061,
   }],
   currentPage: 1,
   totalPages: 1
}

List of your withdraw requests history with thier current status, there is also filter options as always for filtering response results.

Query Parameters

Parameter	Type	Mandatory	Description
asset	String	False	Asset aname.
network	String	False	Network name.
startDate	Number	False	History start date in UNIX based timstamp in milliseconds.
endDate	Number	False	History end date in UNIX based timstamp in milliseconds.
limit	Number	False	List items limit count.
page	String	False	The amount of asswt you want to withdraw.
timestamp	Number	True	The timestamp you made request in milliseconds.

Response Parameters

Parameter	Type	Optional	Description
asset	String	True	Asset name.
network	String	True	Network name.
amount	String	True	The amount of asset that deposits.
priceInBtc	String	True	Amount estimated BTC value.
priceInUsdt	String	True	Amount estimated USDT value.
address	String	True	The destination wallet address.
memo	String	True	Memo (tag) for this transaction.
fee	String	True	The fee amount for this transaction.
txId	String	True	The Tx ID (transaction ID) on associated network.
binanceId	String	True	Transaction Tx ID on ‌Bybit.
internalFeeAction	String	True	Specifies how the fee for internal withdraw will work.
status	String	True	The current status of withdraw.
reason	String	True	The rejection reason if your withdraw get rejected.
createdAt	Number	True	Withdraw start date in UNIX based timstamp in milliseconds.
updatedAt	Number	True	Withdraw updated status date in UNIX based timstamp in milliseconds.

The status with value of PENDING means your withdraw request is in queue for submission, SUBMITTED means that it is submitted successfully on Bybit, CONFIRMED means your withdraw confirmed on Bybit and REJECTED means your withdraw rejected from Bybit, you can find rejection reason in reason parameter.

Trades

Clients Trades History

curl -X GET "https://api.coinlocally.com/api/v1/partners/trades?limit=1&page=1&timestamp=1646411759765"
   -H "x-key: {Your Credential KEY}"
   -H "x-signature: { Data SIGNATURE }"

{
   error: false,
   code: 0,
   result: [{
      side: "Buy",
      createdAt: 1646411759765,
      subAccountId: 24,
      type: "SPOT",
      pair: "BTCUSDT",
      baseQuantity: "23.2398",
      quoteQuantity: "39820290.234",
      commission: "627.52",
      subAccountId: number,
   }],
   currentPage: 1,
   totalPages: 1
}

Get all trades history of your sub accounts. just like transfers history you can use filter options below as well.

HTTP Request

GET /api/v1/partners/trades

Query Parameters

Parameter	Type	Mandatory	Description
subAccountId	Number	False	Your sub account ID.
symbol	String	False	Symbol name.
type	String	False	Trade type (SPOT or USDM_FUTURES)
startDate	Number	False	History start date in UNIX based timstamp in milliseconds.
endDate	Number	False	History end date in UNIX based timstamp in milliseconds.
limit	Number	False	Optional limit for page pagination.
page	Number	False	Optional page number for page pagination.
timestamp	Number	True	The timestamp you made request in milliseconds.

Response Parameters

Parameter	Type	Optional	Description
asset	String	True	Asset name.
network	String	True	Network name.
subAccountId	Number	True	Your sub account ID.
fromAddress	String	True	The Address that asset deposits from.
toAddress	String	True	The Address that asset deposits to.
toMemo	String	True	The memo (tag) of transaction.
amount	String	True	The amount of asset that deposits.
txId	String	True	The Tx ID (transaction ID) on associated network.
status	String	True	The current status of transaction.
createdAt	Number	True	Transaction start date in UNIX based timstamp in milliseconds.
updatedAt	Number	True	Transaction updated status date in UNIX based timstamp in milliseconds.

toMemo is set to null if sender did not set it or the network does not support memo (tag) feature.

status is a enum of PENDING and CONFIRMED that specified current transaction status on that network.

type is an enum of SPOT and USDM_FUTURES values.

Errors

As you already find out, our APIs have a static response structure. when an error occurs the error parameter is set to true with an error code defined in code. you can see error message as well in message parameter.

When code is not 0 it also means that an error occurs. We provide you both boolean style and numeric code style to make your life easier for your error handling implemention :)

And also here is HTTP status codes with their meanings down below:

HTTP	Meaning
401	Unauthorized - You dont have access to the endpoint please use your credentials.
404	Not Found - No content, data or repository found for your request.
409	Conflict - The request data conflicts with the current state of the server.
500	Internal Server Error - An error occurs in our server side application.

HTTP status code of 500 is an odd thing, Please report us if you are involved with this situation with your full request data. thanks !