NAV Navigation
HTTP

Hancock broker API v9.2.0

Scroll down for code samples, example headers and payloads. Select a language for code samples from the tabs above or the mobile navigation menu.

The service will connect to the blockchain when a client connects to the websocket exposed by the service.

The blockchain will be specified in the request by query-param. The fields allowed for the filter are a sender address and/or a contract address. If a sender address is specified, all pending transaction events related to the sender will be captured. If a contract address is specified, all the events programmed in it will be captured. It is mandatory specify at least one filter.

When an event is triggered in the blockchain that meets the requirements of the filter, the service will capture and launch it to the connected client that started the connection through websocket.

Current blockchains supported {dlt} ethereum

Base URLs:

Evented API

Received

transfer

Example payload


{
  "kind": "transaction",
  "body": {
    "blockHash": "0x6c47653f66ac9b733f3b8bf09ed3d300520b4d9c78711ba90162744f5906b1f8",
    "blockNumber": 2812312,
    "transactionId": "0xde8e772f0350e992ddef81bf8f51d94a8ea9216d",
    "from": "0x6c0a14F7561898B9ddc0C57652A53B2C6665443E",
    "to": "0xDe8E772f0350E992Ddef81bF8f51D94A8ea9216d",
    "value": "1",
    "data": "",
    "newContractAddress": null,
    "fee": {
      "amount": "1000000000000000000",
      "decimals": 18,
      "currency": "Ethereum"
    }
  },
  "matchedAddress": "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF"
}

Code Samples

New transfer mined or pending

Event dispatched every time a watched address is related with a transaction of kind "transfer"

Payload

Properties

Events transaction received from the broker each time there is a match between the origin or destination address in blockchain and one address added to the watch list

Name Type Required Description
» kind string true The kind of the received event
» body object true A payload with the transactions fields in HSL (Hancock Specific Language)
»» blockHash string false Hash of the block where this transaction was in
»» blockNumber number false Block number in wich registered the transaction
»» transactionId string false Hash of the transaction
»» from string false Address of the sender in the DLT
»» to string false Address of the receiver in the DLT
»» value string false Value to be transferred
»» data string false Information about the transaction
»» fee object false Fee of transaction
»»» amount string; false Amount of fee. Integer representation
»»» decimals number; false Amount decimals
»»» currency string; false Currency of the fee
»» newContractAddress string false (Optional) Address of the deployed contract
»» timestamp any false Transaction timestamp
» raw any false Raw transaction received from DLT
» matchedAddress string true The address which originated the event

transaction

Example payload


{
  "kind": "transaction",
  "body": {
    "blockHash": "0x6c47653f66ac9b733f3b8bf09ed3d300520b4d9c78711ba90162744f5906b1f8",
    "blockNumber": 2812312,
    "transactionId": "0xde8e772f0350e992ddef81bf8f51d94a8ea9216d",
    "from": "0x6c0a14F7561898B9ddc0C57652A53B2C6665443E",
    "to": "0xDe8E772f0350E992Ddef81bF8f51D94A8ea9216d",
    "value": "1",
    "data": "",
    "newContractAddress": null,
    "fee": {
      "amount": "1000000000000000000",
      "decimals": 18,
      "currency": "Ethereum"
    }
  },
  "matchedAddress": "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF"
}

Code Samples

New generic transaction mined or pending

Event dispatched every time a watched address is related with a transaction.

Payload

Properties

Events transaction received from the broker each time there is a match between the origin or destination address in blockchain and one address added to the watch list

Name Type Required Description
» kind string true The kind of the received event
» body object true A payload with the transactions fields in HSL (Hancock Specific Language)
»» blockHash string false Hash of the block where this transaction was in
»» blockNumber number false Block number in wich registered the transaction
»» transactionId string false Hash of the transaction
»» from string false Address of the sender in the DLT
»» to string false Address of the receiver in the DLT
»» value string false Value to be transferred
»» data string false Information about the transaction
»» fee object false Fee of transaction
»»» amount string; false Amount of fee. Integer representation
»»» decimals number; false Amount decimals
»»» currency string; false Currency of the fee
»» newContractAddress string false (Optional) Address of the deployed contract
»» timestamp any false Transaction timestamp
» raw any false Raw transaction received from DLT
» matchedAddress string true The address which originated the event

contract-transaction

Example payload


{
  "kind": "transaction",
  "body": {
    "blockHash": "0x6c47653f66ac9b733f3b8bf09ed3d300520b4d9c78711ba90162744f5906b1f8",
    "blockNumber": 2812312,
    "transactionId": "0xde8e772f0350e992ddef81bf8f51d94a8ea9216d",
    "from": "0x6c0a14F7561898B9ddc0C57652A53B2C6665443E",
    "to": "0xDe8E772f0350E992Ddef81bF8f51D94A8ea9216d",
    "value": "1",
    "data": "",
    "newContractAddress": null,
    "fee": {
      "amount": "1000000000000000000",
      "decimals": 18,
      "currency": "Ethereum"
    }
  },
  "matchedAddress": "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF"
}

Code Samples

New transaction over a smart contract

Event dispatched when a new transaction of a smartcontract is mined

Payload

Properties

Events transaction received from the broker each time there is a match between the origin or destination address in blockchain and one address added to the watch list

Name Type Required Description
» kind string true The kind of the received event
» body object true A payload with the transactions fields in HSL (Hancock Specific Language)
»» blockHash string false Hash of the block where this transaction was in
»» blockNumber number false Block number in wich registered the transaction
»» transactionId string false Hash of the transaction
»» from string false Address of the sender in the DLT
»» to string false Address of the receiver in the DLT
»» value string false Value to be transferred
»» data string false Information about the transaction
»» fee object false Fee of transaction
»»» amount string; false Amount of fee. Integer representation
»»» decimals number; false Amount decimals
»»» currency string; false Currency of the fee
»» newContractAddress string false (Optional) Address of the deployed contract
»» timestamp any false Transaction timestamp
» raw any false Raw transaction received from DLT
» matchedAddress string true The address which originated the event

contract-deployment

Example payload


{
  "kind": "transaction",
  "body": {
    "blockHash": "0x6c47653f66ac9b733f3b8bf09ed3d300520b4d9c78711ba90162744f5906b1f8",
    "blockNumber": 2812312,
    "transactionId": "0xde8e772f0350e992ddef81bf8f51d94a8ea9216d",
    "from": "0x6c0a14F7561898B9ddc0C57652A53B2C6665443E",
    "to": "0xDe8E772f0350E992Ddef81bF8f51D94A8ea9216d",
    "value": "1",
    "data": "",
    "newContractAddress": null,
    "fee": {
      "amount": "1000000000000000000",
      "decimals": 18,
      "currency": "Ethereum"
    }
  },
  "matchedAddress": "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF"
}

Code Samples

New smart contract deployment

Event dispatched when a new smartcontract is deployed

Payload

Properties

Events transaction received from the broker each time there is a match between the origin or destination address in blockchain and one address added to the watch list

Name Type Required Description
» kind string true The kind of the received event
» body object true A payload with the transactions fields in HSL (Hancock Specific Language)
»» blockHash string false Hash of the block where this transaction was in
»» blockNumber number false Block number in wich registered the transaction
»» transactionId string false Hash of the transaction
»» from string false Address of the sender in the DLT
»» to string false Address of the receiver in the DLT
»» value string false Value to be transferred
»» data string false Information about the transaction
»» fee object false Fee of transaction
»»» amount string; false Amount of fee. Integer representation
»»» decimals number; false Amount decimals
»»» currency string; false Currency of the fee
»» newContractAddress string false (Optional) Address of the deployed contract
»» timestamp any false Transaction timestamp
» raw any false Raw transaction received from DLT
» matchedAddress string true The address which originated the event

contract-event

Example payload


{
  "kind": "event",
  "body": {
    "blockHash": "0x6c47653f66ac9b733f3b8bf09ed3d300520b4d9c78711ba90162744f5906b1f8",
    "blockNumber": 2812312,
    "transactionId": "0xde8e772f0350e992ddef81bf8f51d94a8ea9216d",
    "eventName": "someEvent",
    "returnValues": [
      "value1",
      "value2"
    ],
    "fee": {
      "amount": "1000000000000000000",
      "decimals": 18,
      "currency": "Ethereum"
    }
  },
  "matchedAddress": "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF"
}

Code Samples

New event in a Smart Contract

Event dispatched every time a watched contract fires an event

Payload

Properties

Event of any kind received from the broker every time a watched contract fires an event

Name Type Required Description
» kind string true The kind of the received event
» body object true A payload with the transactions fields in HSL (Hancock Specific Language)
»» blockHash string false Hash of the block where this transaction was in
»» blockNumber number false Block number in wich registered the transaction
»» transactionId string false Hash of the transaction
»» eventName string false Name of the event which has triggered
»» returnValues [string] false Returned values in the event
»» fee object false Fee of transaction
»»» amount string; false Amount of fee. Integer representation
»»» decimals number; false Amount decimals
»»» currency string; false Currency of the fee
»» timestamp any false Transaction timestamp
»» raw any false Raw transaction received from DLT
» matchedAddress string true The address which originated the event

error

Example payload


{
  "error": "400 - 500",
  "internalError": "HKAD5000X",
  "message": "Call Error",
  "extendedMessage": "Error: Description"
}

Code Samples

New error

Event dispatched every time there is an error in the broker service

Payload

Properties

Generic Response Schema

Name Type Required Description
» error string true Identification error code
» internalError string true Hancock error code
» message string false Hancock message
» extendedMessage string false Detailed message

Sent

watch-transfers

Example payload


{
  "kind": "watch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ],
  "status": "mined",
  "consumer": "consumer"
}

Code Samples

Add an address to transfers watch list

Each time that the given address appears in a block transaction of kind "transfers", an event of kind "transfer" will be dispatched back through this channel

Payload

Properties

Commands to add new addresses to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be watched
» status string false The subscription will vary depending on this param (pending transactions, or mined transactionss)
» consumer string false The response will be customized depending on the consumer type

watch-transactions

Example payload


{
  "kind": "watch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ],
  "status": "mined",
  "consumer": "consumer"
}

Code Samples

Add an address to transaction watch list

Each time that the given address appears in a block transaction of any kind, an event of kind "transaction" will be dispatched back through this channel

Payload

Properties

Commands to add new addresses to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be watched
» status string false The subscription will vary depending on this param (pending transactions, or mined transactionss)
» consumer string false The response will be customized depending on the consumer type

watch-contracts-transactions

Example payload


{
  "kind": "watch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ],
  "status": "mined",
  "consumer": "consumer"
}

Code Samples

Add an address or an alias of a smart contract to events watch list

Each time that the contract identified by the given address or alias participate on a transaction, a transaction event will be dispatched back through this channel

Payload

Properties

Commands to add new addresses to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be watched
» status string false The subscription will vary depending on this param (pending transactions, or mined transactionss)
» consumer string false The response will be customized depending on the consumer type

watch-contracts-deployments

Example payload


{
  "kind": "watch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ],
  "status": "mined",
  "consumer": "consumer"
}

Code Samples

Add addresses to transactions watch-list to subscribe to new contract deployments

Each time that a new contract is deployed, a transaction event will be dispatched back through this channel

Payload

Properties

Commands to add new addresses to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be watched
» status string false The subscription will vary depending on this param (pending transactions, or mined transactionss)
» consumer string false The response will be customized depending on the consumer type

watch-contracts-events

Example payload


{
  "kind": "watch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ],
  "status": "mined",
  "consumer": "consumer"
}

Code Samples

Add an address or an alias of a smart contract to events watch list

Each time that the contract identified by the given address or alias dispatch an event, two events of kind "event" and "logs" will be dispatched back through this channel

Payload

Properties

Commands to add new addresses to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be watched
» status string false The subscription will vary depending on this param (pending transactions, or mined transactionss)
» consumer string false The response will be customized depending on the consumer type

unwatch-transfers

Example payload


{
  "kind": "unwatch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ]
}

Code Samples

Delete an address of transfers watch list

Stops the "transfers" alerts of the address.

Payload

Properties

Commands to stop messages for an address, thus deletes the address to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be unwatched

unwatch-transactions

Example payload


{
  "kind": "unwatch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ]
}

Code Samples

Delete an address of transaction watch list

Stops all transactions alerts of the address.

Payload

Properties

Commands to stop messages for an address, thus deletes the address to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be unwatched

unwatch-contracts-transactions

Example payload


{
  "kind": "unwatch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ]
}

Code Samples

Delete an address or an alias of a smart contract to transactions watch list

Stops all transactions contracts alerts of the address.

Payload

Properties

Commands to stop messages for an address, thus deletes the address to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be unwatched

unwatch-contracts-deployments

Example payload


{
  "kind": "unwatch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ]
}

Code Samples

Delete an address from transactions watch-list

Stops all deployments contracts alerts of the address.

Payload

Properties

Commands to stop messages for an address, thus deletes the address to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be unwatched

unwatch-contracts-events

Example payload


{
  "kind": "unwatch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ]
}

Code Samples

Delete an address or an alias of a smart contract to events watch list

Stops all contracts alerts of the address.

Payload

Properties

Commands to stop messages for an address, thus deletes the address to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be unwatched

Schemas

sendMessage

{
  "kind": "watch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ],
  "status": "mined",
  "consumer": "consumer"
}

Properties

Commands to add new addresses to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be watched
» status string false The subscription will vary depending on this param (pending transactions, or mined transactionss)
» consumer string false The response will be customized depending on the consumer type

Enumerated Values

Property Value
kind watch-transfers
kind watch-transactions
kind watch-contracts-transactions
kind watch-contracts-deployments
kind watch-contracts-events
status pending
status mined

sendMessageUnwatch

{
  "kind": "unwatch-transfers",
  "body": [
    "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF",
    "0xd452cb5c4ba4c71ef7c14db0d930dc35c4c97ac7"
  ]
}

Properties

Commands to stop messages for an address, thus deletes the address to the watch list for receiving events related with them

Name Type Required Description
» kind string true The kind of the sent event
» body [string] true Array of addresses to be unwatched

Enumerated Values

Property Value
kind unwatch-transfers
kind unwatch-transactions
kind unwatch-contracts-transactions
kind unwatch-contracts-deployments
kind unwatch-contracts-events

receiveTransactionMessage

{
  "kind": "transaction",
  "body": {
    "blockHash": "0x6c47653f66ac9b733f3b8bf09ed3d300520b4d9c78711ba90162744f5906b1f8",
    "blockNumber": 2812312,
    "transactionId": "0xde8e772f0350e992ddef81bf8f51d94a8ea9216d",
    "from": "0x6c0a14F7561898B9ddc0C57652A53B2C6665443E",
    "to": "0xDe8E772f0350E992Ddef81bF8f51D94A8ea9216d",
    "value": "1",
    "data": "",
    "newContractAddress": null,
    "fee": {
      "amount": "1000000000000000000",
      "decimals": 18,
      "currency": "Ethereum"
    }
  },
  "matchedAddress": "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF"
}

Properties

Events transaction received from the broker each time there is a match between the origin or destination address in blockchain and one address added to the watch list

Name Type Required Description
» kind string true The kind of the received event
» body object true A payload with the transactions fields in HSL (Hancock Specific Language)
»» blockHash string false Hash of the block where this transaction was in
»» blockNumber number false Block number in wich registered the transaction
»» transactionId string false Hash of the transaction
»» from string false Address of the sender in the DLT
»» to string false Address of the receiver in the DLT
»» value string false Value to be transferred
»» data string false Information about the transaction
»» fee object false Fee of transaction
»»» amount string; false Amount of fee. Integer representation
»»» decimals number; false Amount decimals
»»» currency string; false Currency of the fee
»» newContractAddress string false (Optional) Address of the deployed contract
»» timestamp any false Transaction timestamp
» raw any false Raw transaction received from DLT
» matchedAddress string true The address which originated the event

Enumerated Values

Property Value
kind transaction
kind transfer
kind contract-transaction
kind contract-deployment
kind error
currency Ethereum

receiveContractEventMessage

{
  "kind": "event",
  "body": {
    "blockHash": "0x6c47653f66ac9b733f3b8bf09ed3d300520b4d9c78711ba90162744f5906b1f8",
    "blockNumber": 2812312,
    "transactionId": "0xde8e772f0350e992ddef81bf8f51d94a8ea9216d",
    "eventName": "someEvent",
    "returnValues": [
      "value1",
      "value2"
    ],
    "fee": {
      "amount": "1000000000000000000",
      "decimals": 18,
      "currency": "Ethereum"
    }
  },
  "matchedAddress": "0x34C54CB0d5cD1c0f5240324618adAD15ad6646AF"
}

Properties

Event of any kind received from the broker every time a watched contract fires an event

Name Type Required Description
» kind string true The kind of the received event
» body object true A payload with the transactions fields in HSL (Hancock Specific Language)
»» blockHash string false Hash of the block where this transaction was in
»» blockNumber number false Block number in wich registered the transaction
»» transactionId string false Hash of the transaction
»» eventName string false Name of the event which has triggered
»» returnValues [string] false Returned values in the event
»» fee object false Fee of transaction
»»» amount string; false Amount of fee. Integer representation
»»» decimals number; false Amount decimals
»»» currency string; false Currency of the fee
»» timestamp any false Transaction timestamp
»» raw any false Raw transaction received from DLT
» matchedAddress string true The address which originated the event

Enumerated Values

Property Value
kind contract-event
currency Ethereum

genericError

{
  "error": "400 - 500",
  "internalError": "HKAD5000X",
  "message": "Call Error",
  "extendedMessage": "Error: Description"
}

Properties

Generic Response Schema

Name Type Required Description
» error string true Identification error code
» internalError string true Hancock error code
» message string false Hancock message
» extendedMessage string false Detailed message
HTTP