Get started

Hercle APIs uses Websockets to provide real-time access to OTC functionalities for traders and developer.

WEBSOCKET OVERVIEW

Websockets on HercleX utilize SignalR technology. More information about SignalR can be found here. Most major programming languages offer a client SDK for SignalR. Below is a list of packages available for these primary languages:

C#:
 Install-Package Microsoft.AspNetCore.SignalR.Client

Java:

• Maven
  <dependency>
 <groupId>com.microsoft.signalr</groupId>
 <artifactId>signalr</artifactId>
 <version>1.0.0</version>
</dependency>

• Gradle
  implementation 'com.microsoft.signalr:signalr:7.0.0'


Javascript:

• NPM
  https://www.npmjs.com/package/@microsoft/signalr

• From CDN without NPM:
  <script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft-signalr/6.0.1/signalr.js"></script>


C++:
 https://github.com/aspnet/SignalR-Client-Cpp

Python:
 https://pypi.org/project/signalrcore/

AUTHENTICATION

To utilize the public hub, an API key is required. This key ensures that your requests are authenticated, and it's essential for all our hub's endpoints. Before you proceed, ensure that you have completed our onboarding process and that your KYC has been approved. Completing this process is imperative to proceed with the API key creation. To retrieve your API key, follow these steps:

1. Login within out systems following this link.
2. Visit the Account page.
3. Head over to the 'API Key' area.
4. There, you can either generate a new key or retrieve an existing one

A word of advice: Your API key is valuable. Ensure you store it securely and refrain from sharing it publicly or in any insecure spaces.

CONNECTING TO THE HUB, HANDLING COMMANDS AND EVENTS

				
// Establishing a Connection to the Hub
const apiKey = "YOUR_API_KEY";
let connection = new signalR.HubConnectionBuilder()
	.withUrl("${baseUrl}/${hubPath}", { accessTokenFactory: () => apiKey })
	.build();

// Listening for Events
connection.on(eventName, (message) => {
	console.log("Message received from server:", message);
});

// Starting the Connection
connection.start().catch(err => console.error(err));

// Sending Commands
connection.invoke(commandName, commandArguments).catch(err => console.error(err));
				
			

Below are the steps for starting the connection to the hub and handling commands and events with code examples written in JavaScript.

1. Establishing a Connection to the Hub

To initiate your connection with SignalR, you must first establish a "hub connection".

2. Listening for Events

To receive events you need to listen on a specific event name. In the example when an event is received, it's logged to the console.

3. Starting the Connection

Before you send commands or listen to events, ensure that you've started the connection.

4. Sending Commands

Once connected, you can send commands to the server by invoking methods with arguments if required.

HUB RESPONSE

			
Example of hub response:

{
  'channel': 'eventName', 
  'topic': 'topicName', 
  'subject': 'topic.subject', 
  'type': 'message', 
  'clientId': 'clientId',
  'data': '{
    key: value
  }'
}
				
			

Below is a brief description of the fields in a hub's response with an example.

⚠️ HercleX Upgrades Schedule

Regular Upgrade Window

Herclex undergoes scheduled upgrades every Wednesday from 10:00 AM to 11:00 AM GMT+1 time. During this window, users can expect system enhancements and routine maintenance to be carried out.

Urgent Upgrades

In cases where urgent upgrades are necessary outside the scheduled window, efforts will be made to communicate these exceptions in advance. However, the ability to provide prior notice is not guaranteed and will depend on the urgency and critical nature of the upgrade.

Impact on Connectivity

During the upgrade window, if a system upgrade is in progress, a disconnection from SignalR services may occur. It is advisable to anticipate such disconnections and prepare accordingly.

Reconnection Policy Recommendation

It is recommended to implement a reconnection policy to handle disconnections efficiently. This ensures minimal disruption to the user experience during and after the upgrade process.

Reconnection Example

						
// SignalR disconnection handling and reconnection example
  connection.Closed += async (error) =>
  {
  // Log the disconnection event, if necessary
  Console.WriteLine("Disconnected from SignalR. Attempting to reconnect...");

  // Implement a reconnection strategy
  // This example uses a simple delay before attempting to reconnect
  await Task.Delay(new Random().Next(0,5) * 1000);
  await connection.StartAsync();
};
						
				

The provided example, written in C#, showcases a fundamental method for attempting an automatic reconnection after experiencing a disconnection event. It is advisable to tailor the reconnection process to align with the unique needs and circumstances of your application.

For an in-depth exploration of connection lifetime event management in SignalR, including recommended practices for addressing disconnections and reestablishing connections, please consult the official Microsoft documentation: Handling Connection Lifetime Events in SignalR.

API STATUS

You can check the current status of HercleX services and any past incidents by visiting our status page: https://status.hercle.financial.

deprecated

⚠️ WARNING - The following deprecated methods will be permanently removed starting from 07 July 2024. ⚠️

place order

⚠️ WARNING - PlaceOrder is deprecated, please use PlaceOtcOrder instead.

Places an order based on a Price Update ID.
CommandName PlaceOrder
CommandArguments [ ClientId, PriceId, PairName, Price, Side, Size, Slippage ]
eventName executionEvents
subject execution.order.executed

Response Data Example:

'data': '{
  "tradeId":"xxxx",
  "side":"buy",
  "pair":"BTCUSDT",
  "price":26844.07,
  "size":0.01,
  "notional":268.4407,
  "status":1,
  "baseCurrency":"BTC",
  "quoteCurrency":"USDT",
  "timestamp":"2023-10-11T23:00:57.93094Z",
  "statusError":""
}'
                                

ARGUMENTS

ORDER PLACED OBJECT

Get Orders

⚠️ WARNING - GetOrders is deprecated, please use GetOrdersPaginated instead.

Returns an array of the user's orders.
CommandName GetOrders
CommandArguments [ ClientId ]
eventName executionEvents
subject account.orders.snapshot

Response Data Example:

'data': '[
  {
    "orderId": "dcc30a80-88dd-485d-9c3e-d615059bafee",
    "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
    "userId": "3c6765a7-64fd-49d2-a797-7ad61101d836",
    "instrument": "BNBEUR",
    "side": "buy",
    "orderType": 0,
    "price": 541.351787638296,
    "executedPrice": 541.351787638296,
    "executedTimestamp": "2024-03-17T16:09:15.000Z",
    "quantity": 0.05,
    "quantityFilled": 0.05,
    "orderStatus": 2,
    "cancellationReason": "",
    "slippage": 0.1,
    "timestamp":"2024-03-17T16:09:14.000Z",
  }, ...
]'
                                

ARGUMENTS

ORDER OBJECT

historic trades

⚠️ WARNING - GetTrades is deprecated, please use GetTradesPaginated instead.

Returns an array of the user's executed trades.
CommandName GetTrades
CommandArguments [ ClientId ]
eventName executionEvents
subject account.trades.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "userId":"yyyy",
    "instrument": "ETH/EUR",
    "side": "sell",
    "price": 1534,
    "quantityFilled": 0.05,
    "timestamp": "2023-07-23:32:35.000Z",
    "email": "abc@email.it"
  }, ...
]'
                                

ARGUMENTS

TRADE OBJECT

historic withdrawals

⚠️ WARNING - GetWithdraws is deprecated, please use GetWithdrawals instead.

Returns an array of the user's historic withdrawals.
CommandName GetWithdraws
CommandArguments [ ClientId ]
eventName executionEvents
subject account.withdrawals.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
    "userId":"yyyy",
    "name":"Mario",
    "surname":"Rossi",
    "company":"Company",
    "description":null,
    "destination":"zzzz",
    "network":"Ethereum",
    "amount":0.05,
    "asset":"ETH",
    "fee": 5,
    "status":"CONFIRMING",
    "refId":"ab1234",
    "isIstant":false,
    "timestamp":"2023-11-10T15:26:10.586Z"
  }, ...
]'
                                

ARGUMENTS

WITHDRAW OBJECT

historic transactions

⚠️ WARNING - GetTransactions is deprecated, please use GetTransactionsPaginated instead.

Returns an array of the user's historic movements, includint trades, withdrawals and deposits.
CommandName GetTransactions
CommandArguments [ ClientId ]
eventName executionEvents
subject account.transactions.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "userId":"yyyy",
    "sequence":123,
    "type":4,
    "asset":"USDC",
    "amount":1050.32,
    "timestamp":"2023-07-23T12:06:04.175Z"
  }, ...
]'
          

ARGUMENTS

TRANSACTION OBJECT

network fees

⚠️ WARNING - GetWithdrawalInfo is deprecated, please use GetWithdrawals instead.

Returns the network fees for the given asset.
CommandName GetWithdrawalInfo
CommandArguments [ ClientId, Asset ]
eventName executionEvents
subject execution.withdraw.fee.info

Response Data Example:

'data': '{
  "httpStatusCode":200,
  "assetNetworkIds":[{
    "assetId":"BTC",
    "description":"Bitcoin",
    "networkFees":{
      "low":{
        "feePerByte":"214",
        "gasPrice":"",
        "networkFee":"0.00030174",
        "baseFee":"",
        "priorityFee":""
      },
      "medium":{
        "feePerByte":"247",
        "gasPrice":"",
        "networkFee":"0.00034827",
        "baseFee":"",
        "priorityFee":""
      },
      "high":{
        "feePerByte":"283",
        "gasPrice":"",
        "networkFee":"0.00039903",
        "baseFee":"",
        "priorityFee":""
      }
    }
  }]
}'

            

ARGUMENTS

NETWORK FEES OBJECT

NETWORK ID OBJECT

NETWORK FEE OBJECT

get available pairs

Returns an array of supported tradable pairs along with their minimum and maximum sizes.
CommandName GetPairs
CommandArguments [ ClientId ]
eventName executionEvents
subject execution.pairs

Response Data Example:

'data': '[
  {
    "asset": "BTC",
    "currency": "USDT",
    "maxQuoteSize": 200000.0,
    "maxSize": 5.0,
    "minQuoteSize": 50.0,
    "minSize": 0.001,
    "name": "BTCUSDT"
  }, ...
]'
                      

ARGUMENTS

PAIR OBJECT

get asset networks

Returns an array of supported networks for the given asset.
CommandName GetNetworks
CommandArguments [ ClientId, Asset ]
eventName executionEvents
subject execution.asset.networks

Response Data Example:

'data': '[
  "Ethereum",
  "Tron",
  "BNB Smart Chain",
  "Polygon",
  "Optimism",
  "Arbitrum One"
]'
              

ARGUMENTS

ASSET NETWORKS OBJECT

get pair size by amount

Return pair quote size based on base amount
CommandName GetPairSizeByAmount
CommandArguments [ ClientId, pair, side, amount ]
eventName executionEvents
subject execution.pair.price

Response Data Example:

'data': '{
  "id": "xxxx",
  "pair":"BTCUSDT",
  "price":26844.07,
  "size":0.01,
  "timestamp":"2023-10-11T23:00:57.93094Z",
}'
          

ARGUMENTS

PAIR SIZE OBJECT

pair price stream

Subscribe

Subscribes to the real-time feed of price updates of a pair with the selected size.
CommandName SubscribePairPriceChannel
CommandArguments [ ClientId, PairName, Size ]
eventName subscriptions
subject execution.feeds.priceUpdate

Response Data Example:

'data': '{
  "id":"xxxx",
  "buyPrice":26798.50,
  "sellPrice":26790.50,
  "size":1.0,
  "pair":"BTCUSDT",
  "markPrice":26794.575,
  "timestamp":"2023-10-11T23:00:57.93094Z"
}'
              

ARGUMENTS

PRICE UPDATE OBJECT

Unsubscribe

Unsubscribes from an active price feed.
CommandName UnsubscribePairPriceChannel
CommandArguments [ ClientId, PairName, Size ]

ARGUMENTS

place otc order

Places an order based on a Price Update ID.
CommandName PlaceOtcOrder
CommandArguments [ ClientId, PriceId, Side, Slippage ]
eventName executionEvents
subject execution.order.executed

Response Data Example:

'data': '{
  "tradeId":"xxxx",
  "side":"buy",
  "pair":"BTCUSDT",
  "price":26844.07,
  "size":0.01,
  "notional":268.4407,
  "status":1,
  "baseCurrency":"BTC",
  "quoteCurrency":"USDT",
  "timestamp":"2023-10-11T23:00:57.93094Z",
  "statusError":""
}'
                      

ARGUMENTS

ORDER PLACED OBJECT

Get Orders by clientId

Returns an array of the user's orders with a 7 days limit.
CommandName GetOrdersByClientId
CommandArguments [ ClientId, orderClientId ]
eventName executionEvents
subject account.orders.snapshot

Response Data Example:

'data': '[
  {
    "orderId": "dcc30a80-88dd-485d-9c3e-d615059bafee",
    "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
    "userId": "3c6765a7-64fd-49d2-a797-7ad61101d836",
    "instrument": "BNBEUR",
    "side": "buy",
    "orderType": 0,
    "price": 541.351787638296,
    "executedPrice": 541.351787638296,
    "executedTimestamp": "2024-03-17T16:09:15.000Z",
    "quantity": 0.05,
    "quantityFilled": 0.05,
    "orderStatus": 2,
    "cancellationReason": "",
    "slippage": 0.1,
    "timestamp":"2024-03-17T16:09:14.000Z",
  }, ...
]'
                  

ARGUMENTS

ORDER OBJECT

Get Orders paginated

Returns an array of the user's orders with a 7 days limit.
CommandName GetOrdersPaginated
CommandArguments [ ClientId, startDate, endDate, page, pageSize ]
eventName executionEvents
subject account.orders.snapshot

Response Data Example:

'data': '[
  {
    "orderId": "dcc30a80-88dd-485d-9c3e-d615059bafee",
    "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
    "userId": "3c6765a7-64fd-49d2-a797-7ad61101d836",
    "instrument": "BNBEUR",
    "side": "buy",
    "orderType": 0,
    "price": 541.351787638296,
    "executedPrice": 541.351787638296,
    "executedTimestamp": "2024-03-17T16:09:15.000Z",
    "quantity": 0.05,
    "quantityFilled": 0.05,
    "orderStatus": 2,
    "cancellationReason": "",
    "slippage": 0.1,
    "timestamp":"2024-03-17T16:09:14.000Z",
  }, ...
]'
                  

ARGUMENTS

ORDER OBJECT

create rfq

Creates a Request For Quote. Has to be accepted within the time limit through Accept RFQ.
CommandName CreateRequestForQuote
CommandArguments [ ClientId, PairName, Side, Size, Amount ]
eventName executionEvents
subject account.requestForQuote.created

Response Data Example:

'data': '{
  "requestForQuoteId":"xxxx",
  "userId":"xxxx",
  "instrument":"BTCUSDT",
  "baseCurrency":"BTC",
  "quoteCurrency":"USDT",
  "side":"buy",
  "size":0.01,
  "price":26844.07,
  "amount":1.0,
  "status":1,
  "RequestDateTime":"2023-10-11T23:00:57.93094Z",
  "ExpireDateTime":"2023-10-11T23:01:27.87528Z"
}'
                  

ARGUMENTS

RFQ CREATED OBJECT

Create Custom RFQ

Creates a Request For Quote with custom expiration time. Has to be accepted within the time limit through Accept RFQ.
CommandName CreateRequestForQuoteWithCustomExpiration
CommandArguments [ ClientId, PairName, Side, Size, Amount, ExpirationInSeconds ]
eventName executionEvents
subject account.requestForQuote.created

Response Data Example:

'data': '{
  "requestForQuoteId":"xxxx",
  "userId":"xxxx",
  "instrument":"BTCUSDT",
  "baseCurrency":"BTC",
  "quoteCurrency":"USDT",
  "side":"buy",
  "size":0.01,
  "price":26844.07,
  "amount":1.0,
  "status":1,
  "RequestDateTime":"2023-10-11T23:00:57.93094Z",
  "ExpireDateTime":"2023-10-11T23:01:27.87528Z"
}'
                  

ARGUMENTS

RFQ CREATED OBJECT

accept rfq

Accept a previously created Request For Quote.
CommandName AcceptRequestForQuote
CommandArguments [ ClientId, RequestForQuoteId ]
eventName executionEvents
subject execution.order.executed

Response Data Example:

'data': '{
  "tradeId":"xxxx",
  "side":"buy",
  "pair":"BTCUSDT",
  "price":26844.07,
  "size":0.01,
  "notional":268.4407,
  "status":1,
  "baseCurrency":"BTC",
  "quoteCurrency":"USDT",
  "timestamp":"2023-10-11T23:00:57.93094Z",
  "statusError":""
}'
                  

ARGUMENTS

RFQ ACCEPTED OBJECT

get transactions paginated

Returns an array of the user's historic movements, includint trades, withdrawals and deposits with a 7 days limit.
CommandName GetTransactionsPaginated
CommandArguments [ ClientId, startDate, endDate, page, pageSize ]
eventName executionEvents
subject account.transactions.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "userId":"yyyy",
    "sequence":123,
    "type":4,
    "asset":"USDC",
    "amount":1050.32,
    "timestamp":"2023-07-23T12:06:04.175Z"
  }, ...
]'
      

ARGUMENTS

TRANSACTION OBJECT

get historical transactions paginated

Returns an array of the user's historic movements, includint trades, withdrawals and deposits with a 30 days limit.
CommandName GetHistoricalTransactionsPaginated
CommandArguments [ ClientId, startDate, endDate, page, pageSize ]
eventName executionEvents
subject account.transactions.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "userId":"yyyy",
    "sequence":123,
    "type":4,
    "asset":"USDC",
    "amount":1050.32,
    "timestamp":"2023-07-23T12:06:04.175Z"
  }, ...
]'
            

ARGUMENTS

TRANSACTION OBJECT

Get Trades by clientId

Returns an array of the user's executed trades with a 7 days limit.
CommandName GetTradesByClientId
CommandArguments [ ClientId, tradeClientId ]
eventName executionEvents
subject account.trades.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "userId":"yyyy",
    "clientId":"zzzz",
    "instrument": "ETH/EUR",
    "side": "sell",
    "price": 1534,
    "quantityFilled": 0.05,
    "timestamp": "2023-07-23:32:35.000Z",
    "email": "abc@email.it"
  }, ...
]'
            

ARGUMENTS

TRADE OBJECT

get trades paginated

Returns an array of the user's executed trades with a 7 days limit.
CommandName GetTradesPaginated
CommandArguments [ ClientId, startDate, endDate, page, pageSize ]
eventName executionEvents
subject account.trades.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "userId":"yyyy",
    "clientId":"zzzz",
    "instrument": "ETH/EUR",
    "side": "sell",
    "price": 1534,
    "quantityFilled": 0.05,
    "timestamp": "2023-07-23:32:35.000Z",
    "email": "abc@email.it"
  }, ...
]'
            

ARGUMENTS

TRADE OBJECT

get historical trades paginated

Returns an array of the user's executed trades with a 30 days limit.
CommandName GetHistoricalTradesPaginated
CommandArguments [ ClientId, startDate, endDate, page, pageSize ]
eventName executionEvents
subject account.trades.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "userId":"yyyy",
    "clientId":"zzzz",
    "instrument": "ETH/EUR",
    "side": "sell",
    "price": 1534,
    "quantityFilled": 0.05,
    "timestamp": "2023-07-23:32:35.000Z",
    "email": "abc@email.it"
  }, ...
]'
                  

ARGUMENTS

TRADE OBJECT

get balances

Returns informations about the user allocated and available balances.
CommandName GetBalances
CommandArguments [ ClientId ]
eventName executionEvents
subject account.balances.snapshot

Response Data Example:

'data': '{
  "userId":"yyyy",
  "sequence":123,
  "assets":[
    {
      "name":"BTC",
      "available":0.5,
      "allocated":0.0
    },
    {
      "name":"ETH",
      "available":5.0,
      "allocated":0.0
    }, ...
  ],
  "deleted":false
}'
            

ARGUMENTS

BALANCES OBJECT

ASSET OBJECT

withdraw

Sends a withdrawal request.
CommandName WithdrawFunds
CommandArguments [ ClientId, Asset, Amount, DestinationAddress, Network ]
eventName executionEvents
subject account.withdraw.created

Response Data Example:

'data': '{
  "id": "xxxx",
  "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
  "userId": "yyyy", 
  "name" : "Marco",
  "surname": "Rossi",
  "company": "",
  "description": "xyz",
  "destination": "xyzwallet",
  "destinationParams": {},
  "network": "ethereum",
  "amount": 1,
  "asset": "USDT",
  "fee": 5,
  "status":"CONFIRMING",
  "refId": "ab1234",
  "isInstant" : false,
  "timestamp" : "2024-03-27T16:03:12.456Z"
}'
                      

ARGUMENTS

WITHDRAW OBJECT

withdraw funds with address params

Sends a withdrawal request with additional parameters for the destination address.
CommandName WithdrawFundsWithAddressParams
CommandArguments [ ClientId, Asset, Amount, DestinationAddress, DestinationAddressParams, Network, IsInstant ]
eventName executionEvents
subject account.withdraw.created

Response Data Example:

'data': '{
  "id": "xxxx",
  "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
  "userId": "yyyy", 
  "name" : "Marco",
  "surname": "Rossi",
  "company": "",
  "description": "xyz",
  "destination": "xyzwallet",
  "destinationParams": {},
  "network": "ethereum",
  "amount": 1,
  "asset": "USDT",
  "fee": 5,
  "status":"CONFIRMING",
  "refId": "ab1234",
  "isInstant" : false,
  "timestamp" : "2024-03-27T16:03:12.456Z"
}'
                              

ARGUMENTS

WITHDRAW OBJECT

instant withdraw

Sends a instant withdrawal request.
CommandName WithdrawInstantFunds
CommandArguments [ ClientId, Asset, Amount, DestinationAddress, Network ]
eventName executionEvents
subject account.withdraw.created

Response Data Example:

'data': '{
  "id": "xxxx",
  "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
  "userId": "yyyy", 
  "name" : "Marco",
  "surname": "Rossi",
  "company": "",
  "description": "xyz",
  "destination": "xyzwallet",
  "destinationParams": {},
  "network": "ethereum",
  "amount": 1,
  "asset": "USDT",
  "fee": 5,
  "status":"CONFIRMING",
  "refId": "ab1234",
  "isInstant" : false,
  "timestamp" : "2024-03-27T16:03:12.456Z"
}'
                          

ARGUMENTS

WITHDRAW OBJECT

get withdrawals

Returns an array of the user's withdrawals with a 30 days limit.
CommandName GetWithdrawals
CommandArguments [ ClientId ]
eventName executionEvents
subject account.withdrawals.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
    "userId":"yyyy",
    "name":"Mario",
    "surname":"Rossi",
    "company":"Company",
    "description":null,
    "destination":"zzzz",
    "destinationParams": {},
    "network":"Ethereum",
    "amount":0.05,
    "asset":"ETH",
    "fee": 5,
    "status":"CONFIRMING",
    "refId":"ab1234",
    "isInstant":false,
    "timestamp":"2023-11-10T15:26:10.586Z"
  }, ...
]'
                      

ARGUMENTS

WITHDRAW OBJECT

Get withdrawals by clientId

Returns an array of the user's withdrawals with a 7 days limit.
CommandName GetWithdrawalsByClientId
CommandArguments [ ClientId, withdrawClientId ]
eventName executionEvents
subject account.withdrawals.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
    "userId":"yyyy",
    "name":"Mario",
    "surname":"Rossi",
    "company":"Company",
    "description":null,
    "destination":"zzzz",
    "destinationParams": {},
    "network":"Ethereum",
    "amount":0.05,
    "asset":"ETH",
    "fee": 5,
    "status":"CONFIRMING",
    "refId": "ab1234",
    "isInstant" : false,
    "timestamp":"2023-11-10T15:26:10.586Z"
  }, ...
]'
                  

ARGUMENTS

WITHDRAW OBJECT

Get Withdrawals paginated

Returns an array of the user's withdrawals with a 7 days limit.
CommandName GetWithdrawalsPaginated
CommandArguments [ ClientId, startDate, endDate, page, pageSize ]
eventName executionEvents
subject account.withdrawals.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "clientId": "68925acb-4f03-48ab-98a9-16b845f21017",
    "userId":"yyyy",
    "name":"Mario",
    "surname":"Rossi",
    "company":"Company",
    "description":null,
    "destination":"zzzz",
    "destinationParams": {},
    "network":"Ethereum",
    "amount":0.05,
    "asset":"ETH",
    "fee": 5,
    "status":"CONFIRMING",
    "refId": "ab1234",
    "isInstant" : false,
    "timestamp" : "2024-03-27T16:03:12.456Z"
  }, ...
]'
                  

ARGUMENTS

WITHDRAW OBJECT

get whitelisted addresses

Returns an array of the user's whitelisted addresses, both fiat and crypto.
CommandName GetWhitelistedAddresses
CommandArguments [ ClientId ]
eventName executionEvents
subject account.externalAddresses.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "name":"BTC 01",
    "userId":"yyyy",
    "asset":"BTC",
    "address":"zzzz",
    "addressParams": {},
    "network":"Bitcoin",
    "status":0,
    "comment":"",
    "auditBy":"",
    "auditDate":"",
    "enabled":true,
    "deleted":false,
    "creationDate":"2023-10-05T14:07:59+00:00"
  }, ...
]'
            

ARGUMENTS

ADDRESS OBJECT

whitelist address

Sends a request for the whitelisting of a new address.
CommandName WhitelistAddress
CommandArguments [ ClientId, Name, Asset, Address, Network ]
eventName executionEvents
subject account.address.registered

Response Data Example:

'data': '{
  "HttpStatusCode":201,
  "AddressId":"zzzz",
  "Message":""
}'
                  

ARGUMENTS

WHITELISTED ADDRESS OBJECT

whitelist address with params

Sends a request for the whitelisting of a new address with parameters.
CommandName WhitelistAddress
CommandArguments [ ClientId, Name, Asset, Address, Network ]
eventName executionEvents
subject account.address.registered

Response Data Example:

'data': '{
  "HttpStatusCode":201,
  "AddressId":"zzzz",
  "Message":""
}'
                  

ARGUMENTS

WHITELISTED ADDRESS OBJECT

Remove Whitelisted Address

Removes an address from the address whitelist.
CommandName DeleteWhitelistedAddress
CommandArguments [ ClientId, Id ]
eventName executionEvents
subject account.address.deleted

Response Data Example:

'data': '{
  "httpStatusCode":200,
  "addressId":"zzzz",
  "message":""
}'
            

ARGUMENTS

DELETE WHITELISTED ADDRESS OBJECT

create deposit address

Creates a deposit address for the given asset.
CommandName CreateDepositAddress
CommandArguments [ ClientId, Asset, Network ]
eventName executionEvents
subject account.internalAddress.created

Response Data Example:

'data': '{
  "httpStatusCode":200,
  "id":"xxxx",
  "name":"BTC",
  "userId":"yyyy",
  "asset":"BTC",
  "address":"zzzz",
  "network":"Bitcoin",
  "message":""
}'
            

ARGUMENTS

DEPOSIT ADDRESS CREATED OBJECT

get deposit addresses

Returns an array of the user's deposit addresses, both fiat and crypto.
CommandName GetDepositAddress
CommandArguments [ ClientId ]
eventName executionEvents
subject account.internalAddresses.snapshot

Response Data Example:

'data': '[
  {
    "id":"xxxx",
    "name":"EUR",
    "userId":"yyyy",
    "asset":"EUR",
    "address":"zzzz",
    "addressParams": {},
    "network":"Sepa",
    "deleted":false,
    "creationDate":"0001-01-01T00:00:00"
  }, ...
]'
            

ARGUMENTS

DEPOSIT ADDRESS OBJECT

create deposit

⚠️ WARNING - This method is only available in the staging environment and exclusively for the EUR asset.

Creates a fake deposit for the given asset. This method doesn't have a response.
CommandName CreateDeposit
CommandArguments [ Asset, Amount, DepositAddress ]
eventName executionEvents
subject

ARGUMENTS

get payees paginated

Returns an array of the user's payees.
CommandName GetPayeesPaginated
CommandArguments [ ClientId, From, To, Page, PageSize ]
eventName executionEvents
subject banking.payees.snapshot

Response Data Example:

'data': '[
  {
    "id": "id-001",
    "userId": "userId-001",
    "type": 1,
    "name": "John",
    "surname": "Doe",
    "company": "Acme Corp",
    "country": "US",
    "state": "CA",
    "city": "San Francisco",
    "address": "123 Main Street",
    "postalCode": "94105",
    "disabled": false,
    "deleted": false,
    "createdAt": "2025-09-03T11:22:54.000Z"
  }, ...
'
      

ARGUMENTS

Validation Rules

• pageSize: Must be between 5 and 50 items (required)
• Date format: Must follow ISO (e.g., YYYY-MM-DDThh:mm:ssZ)
• Date validation: If both From and To are provided, To must be greater than From
• Date parameters: Both From and To can be null to omit date filtering

PAYEE OBJECT

register payee

Registers a new payee.
CommandName RegisterPayee
CommandArguments [ ClientId, Type, Name, Surname, Company, Country, State, City, Address, PostalCode ]
eventName executionEvents
subject banking.payee.registered

Response Data Example:

'data': '{
  "httpStatusCode": 201,
  "message": "",
  "id": "id-001",
  "type": "Individual",
  "name": "John",
  "surname": "Doe",
  "company": "Acme Corp",
  "country": "US",
  "state": "CA",
  "city": "San Francisco",
  "address": "123 Main Street",
  "postalCode": "94105"
}'
      

ARGUMENTS

RESPONSE OBJECT

get payee addresses paginated

Returns an array of addresses associated with a specific payee.
CommandName GetPayeeAddressesPaginated
CommandArguments [ ClientId, PayeeId, From, To, Page, PageSize ]
eventName executionEvents
subject banking.payee.addresses.snapshot

Response Data Example:

'data': '[
  {
    "id": "id-001",
    "payeeId": "payeeId-001",
    "name": "USDC Wallet",
    "asset": "USDC",
    "address": "address_001",
    "addressParams": {
      "tag": "stable"
    },
    "network": "Ethereum",
    "status": 1,
    "comment": "USDC receiving wallet",
    "auditBy": "System",
    "auditDate": "2025-09-11T17:50:59.000Z",
    "deleted": false,
    "createdAt": "2025-09-11T17:50:59.000Z"
  }, ...
]'
      

ARGUMENTS

Validation Rules

• pageSize: Must be between 5 and 50 items (required)
• Date format: Must follow ISO (e.g., YYYY-MM-DDThh:mm:ssZ)
• Date validation: If both From and To are provided, To must be greater than From
• Date parameters: Both From and To can be null to omit date filtering

PAYEE ADDRESS OBJECT

register payee address

Registers a new address for an existing payee.
CommandName RegisterPayeeAddress
CommandArguments [ ClientId, PayeeId, Name, Asset, Address, AddressParams, Network, Comment ]
eventName executionEvents
subject banking.payee.address.registered

Response Data Example:

'data': '{
  "httpStatusCode": 201,
  "message": "",
  "id": "id_001",
  "payeeId": "e3ab5fc5-fed6-4648-9e69-83c3fcb9e100",
  "name": "USDC Wallet",
  "asset": "USDC",
  "address": "address_001",
  "addressParams": {
    "tag": "stable"
  },
  "network": "Ethereum",
  "comment": "USDC receiving wallet"
}'
      

ARGUMENTS

EUR Network Types

For EUR transfers, the following network types are available:

GBP Network Types

For GBP transfers, the following network types are available:

USD Network Types

For USD transfers, the following network types are available:

Required Address Parameters by Network

Each Currency network type requires specific address parameters:

RESPONSE OBJECT

get transfers paginated

Returns a paginated list of transfers.
CommandName GetTransfersPaginated
CommandArguments [ ClientId, StartDate, EndDate, Page, PageSize ]
eventName executionEvents
subject banking.transfers.snapshot

Response Data Example:

'data': '[
  {
    "id": "id_123456,
    "userId": "userId_123456",
    "clientId": "client123",
    "description": "Monthly payment to supplier",
    "debtor": {
      "internalAddressId": "internal_addr_123",
      "asset": "BTC",
      "address": "address_001",
      "addressParams": {
        "tag": "internal"
      },
      "network": "Bitcoin",
      "amount": 0.001,
      "fee": 0.0001
    },
    "creditor": {
      "payeeAddressId": "payee_addr_456",
      "asset": "BTC", 
      "address": "address_001",
      "addressParams": {
        "memo": "payment123"
      },
      "network": "Bitcoin",
      "amount": 0.0009
    },
    "exchangeInfo": {
      "rate": 1.0
    },
    "status": "Pending",
    "refId": "ref_789xyz",
    "payload": "{\"custom\":\"data\"}",
    "isInstant": false,
    "timestamp": "2025-09-12T14:30:00.000Z"
  }, ...
]'
      

ARGUMENTS

Validation Rules

• Date format: Must follow ISO (e.g., YYYY-MM-DDThh:mm:ssZ)
• Date validation: If both From and To are provided, To must be greater than From
• page: Page number must be 0 or greater
• pageSize: Must be between 5 and 50 items

TRANSFER OBJECT

DEBTOR OBJECT

CREDITOR OBJECT

EXCHANGEINFO OBJECT

transfer

Initiates a transfer of funds to a payee address.
CommandName TransferFunds
CommandArguments [ ClientId, Asset, Amount, InternalAddressId, PayeeAddressId, Description ]
eventName executionEvents
subject banking.transfer.created

Response Data Example:

'data': '{
  "httpStatusCode": 201,
  "message": "Transfer fund request registered successfully",
  "id": "id_123456",
  "asset": "BTC",
  "amount": 0.001,
  "internalAddressId": "internal_addr_123",
  "payeeAddressId": "payee_addr_456",
  "description": "Monthly payment to supplier"
}'
      

ARGUMENTS

Validation Rules

• Description is required and must not exceed 250 characters
• Asset must exist in the configured networks

RESPONSE OBJECT

⚠️ WARNING - This endpoint is only available in the production environment.

get transaction ledger

Retrieves detailed information about a specific transaction, including ledger entries.
CommandName GetTransactionLedger
CommandArguments [ ClientId, TransactionId ]
eventName executionEvents
subject ledger.transaction.details

Response Data Example:

'data': '{
  "httpStatusCode": 200,
  "message": "",
  "id": "tx_123456",
  "refId": "ref_transfer_001",
  "userId": "userId_123456",
  "type": "Transfer",
  "status": "Completed",
  "description": "Monthly payment to supplier",
  "asset": "BTC",
  "amount": 0.001,
  "debtor": {
    "address": "address-001",
    "asset": "BTC",
    "network": "Bitcoin"
  },
  "creditor": {
    "address": "address-001", 
    "asset": "BTC",
    "network": "Bitcoin"
  },
  "timestamp": "2025-09-12T14:30:00.000Z"
}'
      

ARGUMENTS

TRANSACTION LEDGER OBJECT

DEBTOR OBJECT

CREDITOR OBJECT

Errors

The Hercle public hub uses the response field subject to communicate errors. If the subject received in the message is not the expected one, an error has occurred or the request hasn't passed some checks.