NAV
Safeheron API Documents
English | 中文

Introduction

Welcome to Safeheron’s Developer Documentation. Safeheron provides you with various API to manage your team totally on your own and auto optimize your transaction flows. In addition, Safeheron provides Webhook push notification that you can receive team event notices.

Through Safeheron's API, you can:

All transactions will be displayed in Safeheron Console, Transaction History, and Webhook.

Getting Started

Overview

A member with Manage API permission logs into Safeheron Web Console, and then navigates to Settings -> API to configure Webhook and create API accounts. You can access Safeheron API with an API Key obtained from the API account you created.

API Authentication

Safeheron applies a mixed encryption scheme integrating symmetric private key cryptography and asymmetric public key cryptography and uses asymmetric private key to sign the request parameters. AES-256 algorithm is adopted for symmetric encryption algorithm while RSA-4096 algorithm being used for asymmetric encryption algorithm and signature algorithm. The specific procedure is as below:

Safeheron will encrypt and sign the response parameters through the same procedure. You can decrypt and verify the signature as follow:

Generate RSA Private Key via OpenSSL (api_private.pem is your API RSA Private Key):

openssl genpkey -out api_private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:4096

Generate corresponding Public Key to your RSA Private Key via OpenSSL (api_public.pem is your API RSA Public Key):

openssl rsa -in api_private.pem -out api_public.pem -pubout

Note:

IP Whitelisting

Safeheron supports restriction of API calls to be initiated only by whitelisted IP addresses per API key. You need to preset the IP address(es) that can call API when creating your API key.

Example Request

Request Base URL

https://api.safeheron.vip

Request Parameters Before Encryption

Example Request Parameters Before Encryption

{
  "apiKey": "341916e58af445f8aadeb95170218e37",
  "timestamp": "1623038312088",
  "bizContent": {
    "page": 1,
    "pageSize": 1
  }
}

For the specific format, please refer to request parameter of each interface. Please check the right side for the example.

Request Parameters After Encryption

Example Request Parameters After Encryption

{
  "apiKey": "341916e58af445f8aadeb95170218e37",
  "timestamp": "1628652100447",
  "bizContent": "qjFMZXs2n+CxnrNGoaZmGrKQzPosy6QbWEumCMkGOEw=",
  "key": "gYZvuXdJADuaLYMU3z8q5vOtld62PSaPxrrhhr4UGwWbZm7Pw3/VImzHrd3oNy1XT8R55V7pbpQOBVdbmTev/rESnuaXlGofkB04JWAaRCIPytEKMHUNXZXEU9GLVppYst7bgiekMDIDScS4AkD75eDG8zru5Gr+gTxU4AYyHSzB0deQnxmNRemwZn+jaNgNs7WeBcuQWR1Cq2+1At8FlAqF5XzEaeQ3x1Q0N3iaLzSiXHQRYqP1Q6V6/aiIXchin/X9bBRYL618utjm4k0qoXU8Rw2JeEKzn7m2ShyyQQ31zX/rQ1xf0ar5PDtJPU/qYp9Kr4oVtcN6yHdG802nLqpGYlHlMvxy9vpnGFXb9oxh4xYnp0qRUfKLyJIylc3qhq6spHyWnuC5XV1S4lH+rIPNF1icV08ex7pjps2jvTICBzIIPExBamh1n00RcxZbkGqxYfRZ7SLTUCH06EaV5lP8yXNe3fNWjHk4mppaVDj0QFagqTzBM9AwMfHs1dOeDmcwkTacKQsvNRu3l5uZFQYkaUeVB9m3AhKw3lyl2oJIfJgYeBLJEHMGFVZXP92z8+J5KrZEVfkL8F80XkB3sXRP0BiIv/9Mm4VrjopYoDWyXttCysY0lJ9XImRyE7GkSy2sjmW0BCsrECoVHWh73s9o7Kw0uIegFaitch24GsM=",
  "sig": "ZPQcL1aIxMrA6HTq7RWWS8FZS08zSOkS69WohcBw1bDr4Qv2Wkrp2t+PNHMh3TmDUnOmUOiv7mBs/sOw08rhgPHqAU/qtvc1lzJFFOnPp5MBmDgffD1auwm7icGzm3myhEz3hKePxyRgZWB1DpPmMYaRuWt1RYcVmcqRa/Bfd0jR37a35neuOSlaip4jsQE1pHQzQ6itdQhBtZZABl1Plz5u8OaMIDTVj63485zi/n6iuuav+GL+JX2JL6pnWz3CT/9DNqa/McyYbxGswGMBAPgHCptseELVmOQ3ZKNHgMu6EtXEKLzmLeZ5REwnw2MTvpzuy5B1zIuxiafuAhh6Tg=="
}

Public Parameters

Parameter Type Description
apiKey string Unique API key identifier assigned by platform
timestamp string Request timestamp, UNIX millisecond-format string
key string Encrypted data of random AES key by Safeheron API RSA Public Key
sig string Signature data after signing request parameters by your API RSA Private Key
bizContent object AES-encrypted data of request parameters

Example Response

Example Response Encrypted Data

Example Response Encrypted Data

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1628652101098",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "gYZvuXdJADuaLYMU3z8q5vOtld62PSaPxrrhhr4UGwWbZm7Pw3/VImzHrd3oNy1XT8R55V7pbpQOBVdbmTev/rESnuaXlGofkB04JWAaRCIPytEKMHUNXZXEU9GLVppYst7bgiekMDIDScS4AkD75eDG8zru5Gr+gTxU4AYyHSzB0deQnxmNRemwZn+jaNgNs7WeBcuQWR1Cq2+1At8FlAqF5XzEaeQ3x1Q0N3iaLzSiXHQRYqP1Q6V6/aiIXchin/X9bBRYL618utjm4k0qoXU8Rw2JeEKzn7m2ShyyQQ31zX/rQ1xf0ar5PDtJPU/qYp9Kr4oVtcN6yHdG802nLqpGYlHlMvxy9vpnGFXb9oxh4xYnp0qRUfKLyJIylc3qhq6spHyWnuC5XV1S4lH+rIPNF1icV08ex7pjps2jvTICBzIIPExBamh1n00RcxZbkGqxYfRZ7SLTUCH06EaV5lP8yXNe3fNWjHk4mppaVDj0QFagqTzBM9AwMfHs1dOeDmcwkTacKQsvNRu3l5uZFQYkaUeVB9m3AhKw3lyl2oJIfJgYeBLJEHMGFVZXP92z8+J5KrZEVfkL8F80XkB3sXRP0BiIv/9Mm4VrjopYoDWyXttCysY0lJ9XImRyE7GkSy2sjmW0BCsrECoVHWh73s9o7Kw0uIegFaitch24GsM=",
  "data": "fVwpf1ektFjHOAGK5D1Da+uza9AMknD8kmidt4aHL82JrsmxUpBMGq/bC2wX52sIRYgMJ5O/8fQhtvTXqWEmHVLxismG5ffYkkYVYRTAuV2sUMlU7nhmC6nDZzds+SOs81brzoS6INlHMp9pI59y9+FBYty8NR5a57UBo3XIsll1fWCHwt9T3OBoWpWmGFENpNGPPSADt/mDzXQRmDgL5KVGNOu8LkAVZmJCjunmX+41RCuhwdUQSWciv578ZI90cI9rRI5RxcxkVyI5XWZsEhCMoASvOQ3PJ0AkB64UigP+Jjj7oD9BnX+xO+9Tw1kGwdkVikG1aWnAd3/XrdeaRL9ZA/0HYZCHZ2VupoQ7GuEYDQ30iWklI4v6Uoofg+hGY872GVmsyTZNe9GMSYV4go69nd8cDiA39mGTSDZWvQ9VYvpeZiuzZpdS/O2UNv82qfujn0OmKup4RscQ5baXVSOgeS8UQVRmo4d7KWdxi2S5WvriM/MKemKM4myoMVi1jN8k2Bd8S/u5yX16d9KLZM8EBhTLxuo3/lMZn505SFqt9RnvF1qCRVDaDboq6r8V91ZOpciDmJyWrYGKleleBBObFRZ+Ro1UoY3IUiwfr98oTXVgDYE3YtcZjkPBi7IXcZIBz8m/of97aBitUn//og=="
}

Please refer to the right side.

Response Parameters

Parameter Type Description
code int Response result code
message string Response result description
timestamp string Response timestamp, UNIX millisecond-format string
sig string Signature data after signing response parameters by Safeheron API RSA Private Key
key string Encrypted data of random AES key by your API RSA Public Key
bizContent object AES-encrypted data of response parameters

Example Decrypted Data of Response Encrypted Data

[
  {
    "addressBookKey": "8be8c8de4bf749b3b08137ccxefa0b16",
    "addressBookName": "name",
    "whiteLists": [
      {
        "whiteListKey": "fdac862c74734d4fa81d62884f2ce4x0",
        "coinKey": "ETH_ROPSTEN",
        "coinFullName": "Ethereum(Ropsten)",
        "symbol": "ETH",
        "address": "0xCa104eA8CB4722e33a3E68eD4D12x3569594FBC5",
        "urlAddress": "https://ropsten.etherscan.io/address/0xCa104eA8CB4722e33a3E68eD4D12d3569594xBC5",
        "amount": 0,
        "usdAmount": 0,
        "whiteListStatus": "VERIFY_PASS",
        "passNum": 1,
        "signNum": 1,
        "refuseUserName": ""
      }
    ]
  }
]

Example Decrypted bizContent

For the specific format, please refer to response data of each interface.

API List

Wallet Account

The wallet account-related interface allows you to create your wallet and perform wallet-related operations.

List Wallet Accounts

Filter wallet account lists in team according to different combinations of conditions.

HTTP Request

POST /v1/account/list

Request Parameters

Parameter Type Required Description
pageNumber int32 No Page number, start from 1 (default)
pageSize int32 No The number of bars per page, the default is 10, max is 100
hiddenOnUI boolean No Filter whether there are not-displayed wallet accounts in Safeheron App
True: retrieve hidden wallet accounts
False: retrieve displayed wallet accounts
Default: retrieve all wallet accounts
namePrefix string No Filter the response based on this account name prefix
nameSuffix string No Filter the response based on this account name suffix

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "pageNumber": 1,
    "pageSize": 10,
    "totalElements": 100,
    "content": [
      {
        "accountKey": "accountfd9a0bc50c5f4a53b920c7c0ca85e0b7",
        "accountName": "default",
        "accountIndex": 0,
        "accountType": "VAULT_ACCOUNT",
        "hiddenOnUI": false,
        "usdBalance": "0",
        "frozenUsdBalance": "0",
        "amlLockUsdBalance": "0",
        "pubKeys": [
          {
            "signAlg": "secp256k1",
            "pubKey": "03ba5cfed3f88a811f0208570c64d1627af2e8f3363f65aad22be7490469dadd2a"
          }
        ]
      }
    ]
  }
}

Response Data

Parameter Type Description
pageNumber int32 Page number
pageSize int32 The number of bars per page
totalElements int64 Total number of records
content array Data lists per page
└─accountKey string Account Key, the only account identifier
└─accountName string Account name
└─accountIndex int32 Account index
└─accountType string Account type
└─hiddenOnUI boolean Whether display in Safeheron App
True: not display
False: display
└─usdBalance string Account balance, in USD when retrieve
└─frozenUsdBalance string Frozen amount of this account, in USD when retrieve
└─amlLockUsdBalance string Frozen amount by AML of this account, in USD when retrieve
└─pubKeys array Account public key info
     └─signAlg string Signature algorithm, currently supports secp256k1
     └─pubKey string Account compressed public key

Create a Wallet Account

Create a new wallet account.

HTTP Request

POST /v1/account/create

Request Parameters

Parameter Type Required Description
accountName string No Account name, within 30 characters
hiddenOnUI boolean No Whether display in Safeheron App
True: not display
False: display
Default: false

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "accountKey": "account4b8d2c00520646c8862b68420aa1bc55",
    "pubKeys": [
      {
        "signAlg": "secp256k1",
        "pubKey": "03ba5cfed3f88a811f0208570c64d1627af2e8f3363f65aad22be7490469dadd2a"
      }
    ]
  }
}

Response Data

Parameter Type Description
accountKey string Wallet account key
pubKeys array Account public key info
└─signAlg string Signature algorithm, currently supports secp256k1
└─pubKey string Account compressed public key

Batch Create Wallet Accounts V1

Create a batch of wallet accounts based on specified number. Wallet accounts created in batches are not displayed in the Safeheron App by default. The V2 version is recommended.

HTTP Request

POST /v1/account/batch/create

Request Parameters

Parameter Type Required Description
accountName string No The prefix of wallet account name, within 30 characters
count int32 Yes The number of created wallets, greater than 0, max is 100

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "accountKeyList": [
      "account4b8d2c00520646c8862b68420aa1bc55"
    ]
  }
}

Response Data

Parameter Type Description
accountKeyList array Wallet account key

Batch Create Wallet Accounts V2

Create a batch of wallet accounts based on specified number. Wallet accounts created in batches are not displayed in the Safeheron App by default.

HTTP Request

POST /v2/account/batch/create

Request Parameters

Parameter Type Required Description
accountName string No The prefix of wallet account name, within 30 characters
count int32 Yes The number of created wallets, greater than 0, max is 100

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "accountKey": "account4b8d2c00520646c8862b68420aa1bc55",
      "pubKeys": [
        {
          "signAlg": "secp256k1",
          "pubKey": "03ba5cfed3f88a811f0208570c64d1627af2e8f3363f65aad22be7490469dadd2a"
        }
      ]
    }
  ]
}

Response Data

Parameter Type Description
accountKey string Wallet account key
pubKeys array Account public key info
└─signAlg string Signature algorithm, currently supports secp256k1
└─pubKey string Account compressed public key

Change Display of Wallet Account in App

Change wallet account status in Safeheron App.

HTTP Request

POST /v1/account/update/show/state

Request Parameters

Parameter Type Required Description
accountKey string Yes Wallet account key
hiddenOnUI boolean Yes Whether display in Safeheron App
True:not display
False:display

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "result": true
  }
}

Response Data

Parameter Type Description
result boolean Execution result
True: success
False: fail

Add Coins to a Wallet Account

Add one coin to the wallet account and create the default address group for it, then, return the address info in default address group; If the to-add coin already exists in this account, then, return the default address group info of the coin.
In a wallet account, UTXO based coins can add multiple address groups while generally other coins only have one address group. You can check whether the coin supports multi-address adding according to isMultipleAddress in coin info of coin list.

HTTP Request

POST /v1/account/coin/create

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key
accountKey string Yes Account key

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "address": "0x1ec4fb20d8955d9d6a4ae45f01af04e170c0c022",
      "addressType": "DEFAULT",
      "amlLock": "NO"
    }
  ]
}

Response Data

Parameter Type Description
address string Coin receiving address
addressType string Address type
amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen

Batch Add Coins to Wallet Accounts

Designate wallet accounts in batch, add specific coin info to each account, create default address group info for the coin, and then return the address info of default address group. If the coin already existed in the wallet account, then directly return the default address group info of the existing coin.

HTTP Request

POST /v1/account/batch/coin/create

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key
accountKeyList array Yes Account key, max is 100
addressGroupName string No Address group name, within 30 characters

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "addressList": [
        {
          "address": "0x1ec4fb20d8955d9d6a4ae45f01af04e170c0c022",
          "addressType": "DEFAULT",
          "amlLock": "NO"
        }
      ],
      "accountKey": "accountfd9a0bc50c5f4a53b920c7c0ca85e0b7"
    }
  ]
}

Response Data

Parameter Type Description
addressList array Address list
└─address string Coin receiving address
└─addressType string Address type
└─amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
accountKey string Account key

List Wallet Account’s Coins

Retrieve all the coin lists under a wallet account and default address group info of each coin.

HTTP Request

POST /v1/account/coin/list

Request Parameters

Parameter Type Required Description
accountKey string Yes Account key

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "coinKey": "ETH_ROPSTEN",
      "coinFullName": "Ethereum(Ropsten)",
      "coinName": "ETH(Ropsten)",
      "coinDecimal": 18,
      "txRefUrl": "https://ropsten.etherscan.io/tx/{txHash}",
      "addressRefUrl": "https://ropsten.etherscan.io/address/{address}",
      "logoUrl": "https://resource.safeheron.vip/resource/img/logo/1626851355990.png",
      "symbol": "ETH",
      "isMultipleAddress": "NO",
      "feeCoinKey": "ETH_ROPSTEN",
      "feeUnit": "Gwei",
      "feeDecimal": 9,
      "showCoinDecimal": 8,
      "balance": "0",
      "frozenBalance": "0",
      "amlLockBalance": "0",
      "usdBalance": "0",
      "frozenUsdBalance": "0",
      "amlLockUsdBalance": "0",
      "addressList": [
        {
          "address": "0x1ec4fb20d8955d9d6a4ae45f01af04e170c0c022",
          "addressType": "DEFAULT",
          "amlLock": "NO",
          "addressBalance": "0"
        }
      ]
    }
  ]
}

Response Data

Parameter Type Description
coinKey string Coin key
coinFullName string Coin full name
coinName string Coin abbreviation
coinDecimal int32 Coin decimal
txRefUrl string Transaction URL on explorer
addressRefUrl string Block explorer URL
logoUrl string Coin logo URL
symbol string Coin unit
isMultipleAddress string Whether can create multiple address groups
Yes: yes
No: no
feeCoinKey string Coin key of consumed transaction fee for transfer, eg. transfer ERC-20 token, then the consumed transaction fee is ETH.
feeUnit string Transaction fee unit name (Gwei, satoshis)
feeDecimal int32 Fee decimal on Safeheron Console
showCoinDecimal int32 Displayed coin decimal on Safeheron Console
balance string Account balance
frozenBalance string Frozen balance
amlLockBalance string Frozen balance by AML of this account
usdBalance string Account balance, convert it into USD when query
frozenUsdBalance string Frozen amount of this account, in USD when retrieve
amlLockUsdBalance string Frozen amount by AML of this account, in USD when retrieve
addressList array Coin address list
└─address string Coin receiving address
└─addressType string Address type
└─amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
└─addressBalance string The balance of this coin address

List Wallet Account's Coin Address Group

Retrieve all address groups for a coin under the wallet account.

HTTP Request

POST /v1/account/coin/address/list

Request Parameters

Parameter Type Required Description
pageNumber int32 No Page number, start from 1 (default)
pageSize int32 No The number of bars per page, the default is 10, max is 100
coinKey string Yes Coin key
accountKey string Yes Account key

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "pageNumber": 1,
    "pageSize": 10,
    "totalElements": 100,
    "content": [
      {
        "addressGroupKey": "addressffb9910f1f324f06a45ef055748fdf43",
        "addressGroupName": "AddressName",
        "addressList": [
          {
            "address": "0x1ec4fb20d8955d9d6a4ae45f01af04e170c0c022",
            "addressType": "DEFAULT",
            "amlLock": "NO",
            "addressBalance": "0"
          }
        ]
      }
    ]
  }
}

Response Data

Parameter Type Description
pageNumber int32 Page number
pageSize int32 The number of bars per page
totalElements int64 Total number of records
content array Data lists per page
└─addressGroupKey string Address group key
└─addressGroupName string Address group name
└─addressList array Address list
     └─address string Coin receiving address
     └─addressType string Address type
     └─amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
     └─addressBalance string The balance of this coin address

Retrieve The Balance of an Address

Retrieve the balance of a specific coin address.

HTTP Request

POST /v1/account/coin/address/info

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key
address string Yes Coin receiving address

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "address": "0x1ec4fb20d8955d9d6a4ae45f01af04e170c0c022",
    "addressType": "DEFAULT",
    "amlLock": "NO",
    "addressBalance": "0",
    "accountKey": "accountfd9a0bc50c5f4a53b920c7c0ca85e0b7"
  }
}

Response Data

Parameter Type Description
address string Coin receiving address
addressType string Address type
amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
addressBalance string The balance of this coin address
accountKey string Account key

Rename a Wallet Account's Coin Address Group

Rename a coin address group under a wallet account.

HTTP Request

POST /v1/account/coin/address/name

Request Parameters

Parameter Type Required Description
addressGroupKey string Yes Address group key
addressGroupName string Yes Address group name, within 30 characters

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "result": true
  }
}

Response Data

Parameter Type Description
result boolean Execution result
True: success
False: fail

Add Address Group for UTXO-Based Coin

Add a new address group for the UTXO-based coin under a wallet account. If there's no such UTXO-based coin, add the coin first, then add new address group, finally, return the added address information

HTTP Request

POST /v1/account/coin/address/create

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key
accountKey string Yes Account key
addressGroupName string Yes Address group name, within 30 characters

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "address": "0x1ec4fb20d8955d9d6a4ae45f01af04e170c0c022",
      "addressType": "DEFAULT",
      "amlLock": "NO"
    }
  ]
}

Response Data

Parameter Type Description
address string Coin receiving address
addressType string Address type
amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen

Batch Add Address Groups for UTXO-Based Coin

For UTXO-based coin in the wallet account, you can designate wallet account and the number of address group(s) to batch add multiple address groups to this account and then return the added address group info. If there's no this UTXO-based coin in this account, add the coin first and then add its corresponding number of address group(s).

HTTP Request

POST /v1/account/coin/utxo/batch/create

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key
accountKey string Yes Account key
count int32 Yes The number, max is 100
addressGroupName string No Address group name prefix, within 30 characters

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "addressList": [
        {
          "address": "0x1ec4fb20d8955d9d6a4ae45f01af04e170c0c022",
          "addressType": "DEFAULT",
          "amlLock": "NO"
        }
      ],
      "accountKey": "accountfd9a0bc50c5f4a53b920c7c0ca85e0b7"
    }
  ]
}

Response Data

Parameter Type Description
addressList array Address list
└─address string Coin receiving address
└─addressType string Address type
└─amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
accountKey string Account key

Coins

Coin-related interface where you can view the supported coins by Safeheron, coin maintenance info, coin address verification, etc.

Coin List

Retrieve the list of coins supported by Safeheron.

HTTP Request

POST /v1/coin/list

Request Parameters

Parameter Type Required Description

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "coinKey": "ETH_ROPSTEN",
      "coinFullName": "Ethereum(Ropsten)",
      "coinName": "ETH(Ropsten)",
      "coinDecimal": 18,
      "txRefUrl": "https://ropsten.etherscan.io/tx/{txHash}",
      "addressRefUrl": "https://ropsten.etherscan.io/address/{address}",
      "logoUrl": "https://resource.safeheron.vip/resource/img/logo/1626851355990.png",
      "symbol": "ETH",
      "isMultipleAddress": "NO",
      "feeCoinKey": "ETH_ROPSTEN",
      "feeUnit": "Gwei",
      "feeDecimal": 9,
      "showCoinDecimal": 8,
      "coinType": "NATIVE",
      "tokenIdentifier": "NATIVE",
      "minTransferAmount": "1",
      "blockChain": "ethereum",
      "network": "ropsten",
      "gasLimit": 21000,
      "isMemo": "NO",
      "isUtxo": "NO",
      "blockchainType": "EVM"
    }
  ]
}

Response Data

Parameter Type Description
coinKey string Coin key
coinFullName string Coin full name
coinName string Coin abbreviation
coinDecimal int32 Coin decimal
txRefUrl string Transaction URL on explorer
addressRefUrl string Block explorer URL
logoUrl string Coin logo URL
symbol string Coin unit
isMultipleAddress string Whether can create multiple address groups
Yes: yes
No: no
feeCoinKey string Coin key of consumed transaction fee for transfer, eg. transfer ERC-20 token, then the consumed transaction fee is ETH.
feeUnit string Transaction fee unit name (Gwei, satoshis)
feeDecimal int32 Fee decimal on Safeheron Console
showCoinDecimal int32 Displayed coin decimal on Safeheron Console
coinType string Coin type
tokenIdentifier string Contract address, NATIVE is the native asset, non-NATIVE is the contract address
minTransferAmount string Minimum transfer amount, the transfer unit is symbol
blockChain string Blockchain
network string Blockchain network
gasLimit int32 Gas limit set by Safeheron
isMemo string Whether pay MEMO type
Yes: yes
No: no
isUtxo string Whether UTXO-based coin, view UTXO-based coins
Yes: yes
No: no
blockchainType string Blockchain type

Coin Maintenance List

Retrieve the information of coins under maintenance in Safeheron.

HTTP Request

POST /v1/coin/maintain/list

Request Parameters

Parameter Type Required Description

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "coinKey": "ETH_ROPSTEN",
      "maintain": true,
      "title": "ETH Maintenance",
      "content": "We will maintain ETH tokens during xxx-xxx",
      "startTime": "1635170400000",
      "endTime": "1635199200000"
    }
  ]
}

Response Data

Parameter Type Description
coinKey string Coin key
maintain boolean Under maintenance or not
title string Maintenance title
content string Content
startTime string Coin maintenance start time, UNIX time in milliseconds
endTime string Coin maintenance end time, UNIX time in milliseconds

Check Coin Address

Check the accuracy of the coin address according to the incoming verification fields.

HTTP Request

POST /v1/coin/address/check

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key
address string Yes Coin receiving address
checkContract boolean No Check if it's contract address
True: check
False: not to check
checkAml boolean No Check its AML validity
True: check
False: not to check
checkAddressValid boolean No Check validity of address format
True: check
False: not to check

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "addressValid": true,
    "contract": true,
    "amlValid": true
  }
}

Response Data

Parameter Type Description
addressValid boolean Whether valid address format
True: valid address
False: invalid address
contract boolean Contract address or not
True: contract address
False: non-contract address
amlValid boolean Limit by risk control or not
True: AML valid address
False: AML blacklisted address

Snapshot the Coin Balance

Safeheron will snapshot the coin balance of the day when the transaction block is created (GMT+8). You can search a specific date to see the snapshot of coin balance on the day.

HTTP Request

POST /v1/coin/balance/snapshot

Request Parameters

Parameter Type Required Description
gmt8Date string Yes yyyy-MM-dd string (GMT+8)

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "coinKey": "ETH_ROPSTEN",
      "coinBalance": "0"
    }
  ]
}

Response Data

Parameter Type Description
coinKey string Coin key
coinBalance string Coin balance, the unit is the symbol returned by the coin list

Retrieve the Current Block Height of a Coin

Retrieve the current block height for a coin according to the incoming coin key.

HTTP Request

POST /v1/coin/block/height

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key, multiple coin keys are separated by commas

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "coinKey": "ETH_ROPSTEN",
      "localBlockHeight": 0
    }
  ]
}

Response Data

Parameter Type Description
coinKey string Coin key
localBlockHeight int64 Coin's current block height

Transaction

Transaction-related interfaces for transaction information, creating transactions, speeding up, cancelling, etc.

Transaction List

Filter transaction history of the team by different condition combinations.

HTTP Request

POST /v1/transactions/list

Request Parameters

Parameter Type Required Description
pageNumber int32 No Page number, start from 1 (default)
pageSize int32 No The number of bars per page, the default is 10, max is 100
sourceAccountKey string No Source account key
sourceAccountType string No Source account type
destinationAccountKey string No Destination account key
destinationAccountType string No Destination account type
createTimeMin int64 No Start time for creating a transaction, UNIX timestamp (ms)
createTimeMax int64 No End time for creating a transaction, UNIX timestamp (ms)
txAmountMin string No Min transaction amount
txAmountMax string No Max transaction amount
coinKey string No Coin key, multiple coin keys are separated by commas
feeCoinKey string No Transaction fee coin key, multiple coin keys are separated by commas
transactionStatus string No Transaction status
transactionSubStatus string No Transaction substatus
completedTimeMin int64 No Min duration for completing a transaction, UNIX timestamp (ms)
completedTimeMax int64 No Max duration for completing a transaction, UNIX timestamp (ms)
customerRefId string No Merchant unique business ID
realDestinationAccountType string No Type of actual destination account
hideSmallAmountUsd string No Custom filtering amount, only return query result of transactions greater than this amount (in USD)

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "pageNumber": 1,
    "pageSize": 10,
    "totalElements": 100,
    "content": [
      {
        "txKey": "tx46461daa9b7a4612abce99e7ce598844",
        "txHash": "0xf7292ea446b573bab7311921e2489fb29d26ec393f2d6c8e280a7157f635234",
        "coinKey": "ETH_ROPSTEN",
        "txAmount": "0.001",
        "sourceAccountKey": "account4b8d2c00520646c8862b68420aa1234234",
        "sourceAccountType": "VAULT_ACCOUNT",
        "sourceAddress": "0xCa104eA8CB4722e33a3E68eD4D12d3569594FBC5",
        "destinationAccountKey": "6553009588f443b1970a5962590a2158",
        "destinationAccountType": "WHITELISTING_ACCOUNT",
        "destinationAddress": "0xCa104eA8CB4722e33a3E68eD4D12d3569594F234234",
        "destinationTag": "TEST",
        "transactionStatus": "COMPLETED",
        "transactionSubStatus": "CONFIRMED",
        "createTime": 1626075236000,
        "note": "Initiate transaction",
        "auditUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
        "createdByUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
        "txFee": "0.000106841386050000",
        "feeCoinKey": "ETH_ROPSTEN",
        "replaceTxHash": "0x628626531285bb90d4130d3beb3c355d2a7fe0bdfa1fa05e3431f15340aafeb6",
        "customerRefId": "a1ef6672-c231-43cc-b174-ff30d392e723",
        "customerExt1": "1",
        "customerExt2": "2",
        "amlLock": "NO",
        "blockHeight": 10000000,
        "completedTime": 1626075236000,
        "realDestinationAccountType": "VAULT_ACCOUNT",
        "transactionSubStatusDesc": "Confirmed",
        "txAmountToUsd": "19.9813552",
        "sourceAccountName": "wallet1",
        "sourceAccountTypeName": "vault",
        "destinationAccountName": "API transaction group",
        "destinationAccountTypeName": "Whitelisted address",
        "auditUserName": "test",
        "createdByUserName": "test"
      }
    ]
  }
}

Response Data

Parameter Type Description
pageNumber int32 Page number
pageSize int32 The number of bars per page
totalElements int64 Total number of records
content array Data lists per page
└─txKey string Transaction key
└─txHash string Transaction hash
└─coinKey string Coin key
└─txAmount string Transaction amount, the unit is the symbol returned by the coin list
└─sourceAccountKey string Source account key
└─sourceAccountType string Source account type
└─sourceAddress string Source address
└─destinationAccountKey string Destination account key
└─destinationAccountType string Destination account type
└─destinationAddress string Destination address
└─destinationTag string If the destination is tag or memo type, then this value is empty
└─transactionStatus string Transaction status
└─transactionSubStatus string Transaction substatus
└─createTime int64 Transaction creation time, UNIX timestamp (ms)
└─note string Note
└─auditUserKey string Final approver key
└─createdByUserKey string Creator key
└─txFee string Transaction fee
└─feeCoinKey string Coin key of consumed transaction fee for transfer, eg. transfer ERC-20 token, then the consumed transaction fee is ETH.
└─replaceTxHash string Quoted transaction hash (only for the sped-up transaction)
└─customerRefId string Merchant unique business ID
└─customerExt1 string Merchant extended field
└─customerExt2 string Merchant extended field
└─amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
└─blockHeight int64 Block height (for confirming transaction and succeeded transaction)
└─completedTime int64 Transaction completion time
└─realDestinationAccountType string Type of actual destination account
└─transactionSubStatusDesc string Transaction substatus description
└─txAmountToUsd string Amount in USD when transact
└─sourceAccountName string Source account name
└─sourceAccountTypeName string Source account type name
└─destinationAccountName string Destination account name
└─destinationAccountTypeName string Destination account type name
└─auditUserName string Final approver username
└─createdByUserName string Creator username

Create a Transaction

Create a new transaction.

HTTP Request

POST /v2/transactions/create

Request Parameters

Parameter Type Required Description
customerRefId string Yes Merchant unique business ID (within 100 characters)
customerExt1 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
customerExt2 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
note string No Transaction note (within 180 characters)
coinKey string Yes Coin key
txFeeLevel string No Transaction Fee Rate Grade
Choose between the transaction fee rate. If the transaction fee rate is preset, this one will be the priority.
feeRateDto object No Transaction fee rate, either txFeeLevel or feeRateDto
└─feeRate string No Fee rate: UTXO feePerByte, EVM gasPrice, TRON feeLimit (no fee rate for TRON)
└─gasLimit string No EVM gasLimit
└─maxPriorityFee string No EIP-1559 maxPriorityFee
└─maxFee string No EIP-1559 maxFee
maxTxFeeRate string No Max estimated transaction fee rate for setting transaction fee rate grade
txAmount string Yes Transaction amount
sourceAccountKey string Yes Source account key
sourceAccountType string Yes Account type
destinationAccountKey string No Destination account key
Address book key if the destination is whitelisted account
Wallet account key if the destination is wallet account
No key for unknown address
destinationAccountType string Yes Destination account type
destinationAddress string Yes Destination address, if not uploaded, use destination account's default address
destinationTag string No Destination Tag
isRbf boolean No Enable BTC RBF (Replace-by-fee, a protocol for Bitcoin memory pool, is used have other transaction replace the unconfirmed transaction)
failOnContract boolean No Default is [true]. The parameter decides on creating the transaction or not when the destination is a contract address. If it's [false], then the transaction can be created when the target is a contract address. If it's [true], the transaction can be created but will fail in the end.
nonce int64 No Custom nonce
balanceVerifyType string No Balance verification, BALANCE_CHECK by default

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "txKey": "tx46461daa9b7a4612abce99e7ce598844"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key

EVM- & UTXO-Transaction Speed-Up

For broadcasting transactions with lower transaction fees, speed-up is available for transactions which are not on the chain for a long time. Speed up EVM-transactions will apply BTC RBF (set isRbf = true when creating the transaction, the speed-up will be RBF speed-up, or will be CPFP speed-up), and other UTXO-transactions will be under CPFP speed-up.

HTTP Request

POST /v2/transactions/recreate

Request Parameters

Parameter Type Required Description
txKey string Yes Transaction key
txHash string Yes Transaction hash
coinKey string Yes Coin key
txFeeLevel string No Transaction Fee Rate Grade
Choose between the transaction fee rate. If the transaction fee rate is preset, this one will be the priority.
feeRateDto object No Transaction fee rate, either txFeeLevel or feeRateDto
└─feeRate string No Fee rate: UTXO feePerByte, EVM gasPrice, TRON feeLimit (no fee rate for TRON)
└─gasLimit string No EVM gasLimit
└─maxPriorityFee string No EIP-1559 maxPriorityFee
└─maxFee string No EIP-1559 maxFee

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "txKey": "tx46461daa9b7a4612abce99e7ce598844"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key

Retrieve a Transaction

Retrieve a transaction, either customerRefId or txKey are required. If both have values, the retrieval will be according to txKey.

HTTP Request

POST /v1/transactions/one

Request Parameters

Parameter Type Required Description
txKey string No Transaction key
customerRefId string No Merchant unique business ID (within 100 characters)

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "txKey": "tx46461daa9b7a4612abce99e7ce598844",
    "txHash": "0xf7292ea446b573bab7311921e2489fb29d26ec393f2d6c8e280a7157f635234",
    "coinKey": "ETH_ROPSTEN",
    "txAmount": "0.001",
    "sourceAccountKey": "account4b8d2c00520646c8862b68420aa1234234",
    "sourceAccountType": "VAULT_ACCOUNT",
    "sourceAddress": "0xCa104eA8CB4722e33a3E68eD4D12d3569594FBC5",
    "destinationAccountKey": "6553009588f443b1970a5962590a2158",
    "destinationAccountType": "WHITELISTING_ACCOUNT",
    "destinationAddress": "0xCa104eA8CB4722e33a3E68eD4D12d3569594F234234",
    "destinationTag": "TEST",
    "transactionStatus": "COMPLETED",
    "transactionSubStatus": "CONFIRMED",
    "createTime": 1626075236000,
    "note": "Initiate transaction",
    "auditUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "createdByUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "txFee": "0.000106841386050000",
    "feeCoinKey": "ETH_ROPSTEN",
    "replaceTxHash": "0x628626531285bb90d4130d3beb3c355d2a7fe0bdfa1fa05e3431f15340aafeb6",
    "customerRefId": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "customerExt1": "1",
    "customerExt2": "2",
    "amlLock": "NO",
    "blockHeight": 10000000,
    "completedTime": 1626075236000,
    "realDestinationAccountType": "VAULT_ACCOUNT",
    "transactionSubStatusDesc": "Confirmed",
    "txAmountToUsd": "19.9813552",
    "sourceAccountName": "wallet1",
    "sourceAccountTypeName": "Vault",
    "destinationAccountName": "API transaction group",
    "destinationAccountTypeName": "Whitelisted address",
    "auditUserName": "test",
    "createdByUserName": "test"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key
txHash string Transaction hash
coinKey string Coin key
txAmount string Transaction amount, the unit is the symbol returned by the coin list
sourceAccountKey string Source account key
sourceAccountType string Source account type
sourceAddress string Source address
destinationAccountKey string Destination account key
destinationAccountType string Destination account type
destinationAddress string Destination address
destinationTag string If the destination is tag or memo type, then this value is empty
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
createTime int64 Transaction creation time, UNIX timestamp (ms)
note string Note
auditUserKey string Final approver key
createdByUserKey string Creator key
txFee string Transaction fee
feeCoinKey string Coin key of consumed transaction fee for transfer, eg. transfer ERC-20 token, then the consumed transaction fee is ETH.
replaceTxHash string Quoted transaction hash (only for the sped-up transaction)
customerRefId string Merchant unique business ID
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
blockHeight int64 Block height (for confirming transaction and succeeded transaction)
completedTime int64 Transaction completion time
realDestinationAccountType string Type of actual destination account
transactionSubStatusDesc string Transaction substatus description
txAmountToUsd string Amount in USD when transact
sourceAccountName string Source account name
sourceAccountTypeName string Source account type name
destinationAccountName string Destination account name
destinationAccountTypeName string Destination account type name
auditUserName string Final approver username
createdByUserName string Creator username

Estimate Transaction Fee

When create or speed up a transaction, this interface can give an estimated range of transaction fee rates in corresponding coin for choosing a proper fee rate to transact.

HTTP Request

POST /v2/transactions/getFeeRate

Request Parameters

Parameter Type Required Description
coinKey string Yes Coin key
txHash string No Transaction hash, pass the original transaction hash when speed up transaction estimation
sourceAddress string No Source address, which is required when estimating transaction fee for TRON; and it is required when obtaining on-chain gas limit for EVM chains, or Safeheron will return the default value
destinationAddress string No Destination address, can be set when retrieve estimated transaction fee for TRON (optional, estimated fee can be more precise if set); and it is required when obtaining on-chain gas limit for EVM chains, or Safeheron will return the default value
value string No Amount of transfer, if this field has a value, the gas limit calculated can be more precise

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "feeUnit": "Gwei",
    "highFeeRate": {
      "baseFee": "0.000049522",
      "fee": null,
      "feeRate": "2.000049522",
      "gasLimit": "22000",
      "maxFee": "2.000112945",
      "maxPriorityFee": "2"
    },
    "lowFeeRate": {
      "baseFee": "0.000049522",
      "fee": null,
      "feeRate": "1.100049522",
      "gasLimit": "22000",
      "maxFee": "1.100055713",
      "maxPriorityFee": "1.1"
    },
    "middleFeeRate": {
      "baseFee": "0.000049522",
      "fee": null,
      "feeRate": "1.500049522",
      "gasLimit": "22000",
      "maxFee": "1.500079325",
      "maxPriorityFee": "1.5"
    },
    "minFeeRate": {
      "baseFee": "0.000049522",
      "fee": null,
      "feeRate": "1.000049522",
      "gasLimit": "22000",
      "maxFee": "1.000049522",
      "maxPriorityFee": "1"
    }
  }
}

Response Data

Parameter Type Description
feeUnit string Fee rate unit
minFeeRate object Minimum fee rate
lowFeeRate object Fee rate when the transaction fee rate is low
middleFeeRate object Fee rate when the transaction fee rate is medium
highFeeRate object Fee rate when the transaction fee rate is high
└─feeRate string Fee rate, UTXO feePerByte, EVM gasPrice and TRON feeLimit
└─fee string Estimated transaction fee for TRON, only for TRON
└─gasLimit string EVM gasLimit
└─baseFee string EIP-1559 baseFee
└─maxPriorityFee string EIP-1559 maxPriorityFee
└─maxFee string EIP-1559 maxFee, different from maxTxFeeRate in API

Cancel Transaction

Cancel the authorization-pending transaction.

HTTP Request

POST /v1/transactions/cancel

Request Parameters

Parameter Type Required Description
txKey string Yes Transaction key
txType string No Transaction type, TRANSACTION by default

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "result": true
  }
}

Response Data

Parameter Type Description
result boolean Execution result
True: success
False: fail

UTXO-Based Coin Sweeping

For wallet account's UTXO-based coin which has multiple addresses, this interface can sweep certain qualified addresses into the specific address.

HTTP Request

POST /v1/transactions/utxo/collection

Request Parameters

Parameter Type Required Description
customerRefId string Yes Merchant unique business ID (within 100 characters)
customerExt1 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
customerExt2 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
note string No Transaction note (within 180 characters)
coinKey string Yes Coin key
txFeeRate string No Transaction fee rate, the unit is the feeUnit returned by the coin list
txFeeLevel string No Transaction Fee Rate Grade
Choose between the transaction fee rate. If the transaction fee rate is preset, this one will be the priority.
maxTxFeeRate string No Max estimated transaction fee rate for setting transaction fee rate grade
minCollectionAmount string No Min sweeping amount
sourceAccountKey string Yes Source wallet account key
sourceAccountType string Yes Account type, pass value VAULT_ACCOUNT
destinationAccountKey string Yes Destination wallet account key
destinationAccountType string Yes Destination account type, pass value VAULT_ACCOUNT
destinationAddress string No Destination address
destinationTag string No Destination Tag

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "txKey": "tx46461daa9b7a4612abce99e7ce598844",
    "collectionAmount": "1",
    "collectionNum": 10
  }
}

Response Data

Parameter Type Description
txKey string Transaction key
collectionAmount string Sweeping amount, the unit is the symbol returned by the coin list
collectionNum int32 Number of sweeps

Web3 API

Web3 API Introduction

Safeheron offers institutional-level clients secure governance for universal multi-signature approval of Web3 application scenarios such as DeFi, NFTs, etc. You can automate your Web3 enterprise by linking DeFi, NFTs, etc. The API allows Web3 applications to initiate Web3 transactions.

The following APIs are supported:

  1. eth_sign
  2. personal_sign
  3. eth_signTypedData
  4. eth_signTransaction

Create a Web3 Wallet Account

Create a new Web3 wallet account.

HTTP Request

POST /v1/web3/account/create

Request Parameters

Parameter Type Required Description
accountName string No Account name, within 30 characters
hiddenOnUI boolean No Whether display in Safeheron App
True: not display
False: display
Default: false

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "accountKey": "account66c6380427e64537b85c5f23aec56272",
    "pubkeyList": [
      {
        "signAlg": "secp256k1",
        "pubkey":    "02c165c9a481f6a12eabe0d417ca6e7d04e762c5786afdf55c8c5716a1214b8cbf"           }
    ],
    "addressList": [
      {
        "blockchainType": "EVM",
        "address": "0x111111111111111111111111111"
      }
    ]
  }
}

Response Data

Parameter Type Description
accountKey string Account Key, the only account identifier
pubKeyList array Account public key info
└─signAlg string Signature algorithm, currently supports secp256k1
└─pubKey string Account compressed public key
addressList array Address list
└─blockchainType string Blockchain Type
└─address string Coin receiving address

Batch Web3 Wallet Account Creation

Create a batch of wallet accounts based on specified number. Web3 Wallet accounts created in batches are not displayed in the Safeheron App by default.

HTTP Request

POST /v1/web3/batch/account/create

Request Parameters

Parameter Type Required Description
accountName string No The prefix of wallet account name, within 30 characters
count int32 Yes The number of created wallets, greater than 0, max is 100

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "accountKey": "account66c6380427e64537b85c5f23aec56272",
      "pubkeyList": [
        {
          "signAlg": "secp256k1",
          "pubkey":    "02c165c9a481f6a12eabe0d417ca6e7d04e762c5786afdf55c8c5716a1214b8cbf"           }
      ],
      "addressList": [
        {
          "blockchainType": "EVM",
          "address": "0x111111111111111111111111111"
        }
      ]
    }
  ]
}

Response Data

Parameter Type Description
accountKey string Account Key, the only account identifier
pubKeyList array Account public key info
└─signAlg string Signature algorithm, currently supports secp256k1
└─pubKey string Account compressed public key
addressList array Address list
└─blockchainType string Blockchain Type
└─address string Coin receiving address

List Web3 Wallet Accounts

Filter Web3 wallet account lists in team according to different combinations of conditions.

HTTP Request

POST /v1/web3/account/list

Request Parameters

Parameter Type Required Description
direct string No Page query direction, NEXT by default
limit int32 No The amount of items to retrieve at a time, the default max value is 500
fromId string No accountKey of the first transaction history. If the accountKey of transaction history has no set value, the starting page is the first page by default

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "accountName": "wallet 11",
      "accountKey": "account2024152bd65d4eaa85a26e57497562c1",
      "hiddenOnUI": false,
      "pubkeyList": [
        {
          "signAlg": "secp256k1",
          "pubkey": "02226320f7571a5b1f2d56f3f1d1b6c4efce9a1a882f8f42bfc37bc7d1f3848cc2"
        }
      ],
      "addressList": [
        {
          "blockchainType": "EVM",
          "address": "0x111111111111111111111111111"
        }
      ]
    }
  ]
}

Response Data

Parameter Type Description
accountKey string Account Key, the only account identifier
accountName string Account name
hiddenOnUI boolean Whether display in Safeheron App
True: not display
False: display
pubKeyList array Account public key info
└─signAlg string Signature algorithm, currently supports secp256k1
└─pubKey string Account compressed public key
addressList array Address list
└─blockchainType string Blockchain Type
└─address string Coin receiving address

Create ethSign

Through this interface, merchants can initiate ethSign signatures. The merchant must transmit the transaction data, generate a hash of the transaction data (both 0x and non-0x prefix data formats are supported), and submit the hash through this interface to create a signature. The signature result can be obtained by querying the single Web3 signature interface or webhook.

HTTP Request

POST /v1/web3/sign/ethSign

Request Parameters

Parameter Type Required Description
accountKey string Yes Source account key
customerRefId string Yes Merchant unique business ID (within 100 characters)
note string No Note
customerExt1 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
customerExt2 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
messageHash object Yes Message Hash
└─chainId int64 Yes Chain ID (Does not participate in signing, only hash participates in signing)
└─hash array Yes Hash to be signed, hexadecimal string (only one is supported for now)

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent":
  {
    "txKey": "tx7dacce99c5f249b6bf486214596a5458"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key

Create personalSign

Through this interface, the merchant can initiate a personalSign signature of any text. The merchant only needs to prepare the data to be signed and submit it through this interface to create a signature. The signature result can be obtained by querying the single Web3 signature interface or webhook, and the subsequent process of obtaining the signature is done independently by the merchant based on their own needs.

HTTP Request

POST /v1/web3/sign/personalSign

Request Parameters

Parameter Type Required Description
accountKey string Yes Source account key
customerRefId string Yes Merchant unique business ID (within 100 characters)
note string No Note
customerExt1 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
customerExt2 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
message object Yes Message
└─chainId int64 Yes Chain ID (Does not participate in signing, only data participates in signing)
└─data string Yes Data to be signed

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent":
  {
    "txKey": "tx7dacce99c5f249b6bf486214596a5458"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key

Create ethSignTypedData

Through this interface, the merchant can initiate ethSignTypedData signatures for specific format data (Support v1, v3 and v4 data formats). To create a signature, the merchant must independently complete the format encapsulation of the signature data and submit the specific format of the data to be signed through this interface.

HTTP Request

POST /v1/web3/sign/ethSignTypedData

Request Parameters

Parameter Type Required Description
accountKey string Yes Source account key
customerRefId string Yes Merchant unique business ID (within 100 characters)
note string No Note
customerExt1 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
customerExt2 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
message object Yes Message
└─chainId int64 Yes Chain ID (Does not participate in signing, only data participates in signing)
└─data string Yes Data to be signed
└─version string Yes EthSignTypedData Version

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent":
  {
    "txKey": "tx7dacce99c5f249b6bf486214596a5458"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key

Create ethSignTransaction

Through this interface, the merchant can initiate ethSignTransaction signature transactions. The merchant must prepare transaction-related data such as from, to, nonce, gasLimit, gasPrice, value, data, and so on, and submit the transaction data through this interface to create a signature. The signature result can be obtained by querying the single Web3 signature interface or webhook, where the subsequent process of obtaining the signature is done independently by the merchant based on their own requirements.

HTTP Request

POST /v1/web3/sign/ethSignTransaction

Request Parameters

Parameter Type Required Description
accountKey string Yes Source account key
customerRefId string Yes Merchant unique business ID (within 100 characters)
note string No Note
customerExt1 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
customerExt2 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
transaction object Yes Transaction
└─to string No To
└─value string Yes Value (Unit: wei)
└─chainId int64 Yes Chain ID
└─gasPrice string No Gas price
└─gasLimit int32 Yes Gas limit
└─maxPriorityFeePerGas string No Max priority fee per gas for EIP-1559
└─maxFeePerGas string No Max fee per gas for EIP-1559
└─nonce int64 Yes Nonce
└─data string No Data

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent":
  {
    "txKey": "tx7dacce99c5f249b6bf486214596a5458"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key

Cancel Sign

Cancel the authorization-pending sign.

HTTP Request

POST /v1/web3/sign/cancel

Request Parameters

Parameter Type Required Description
txKey string Yes Transaction key

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "result": true
  }
}

Response Data

Parameter Type Description
result boolean Execution result
True: success
False: fail

Retrieve a Web3 Sign

Retrieve a specific Web3 Sign. Either customerRefId or txKey is required. If the both have values, then retrieve according to txKey.

HTTP Request

POST /v1/web3/sign/one

Request Parameters

Parameter Type Required Description
txKey string No Transaction key
customerRefId string No Merchant unique business ID (within 100 characters)

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent":
  {
    "txKey":null,
    "accountKey":null,
    "sourceAddress":null,
    "transactionStatus":null,
    "transactionSubStatus":null,
    "createdByUserKey":null,
    "createdByUserName":null,
    "createTime":null,
    "auditUserKey":null,
    "auditUserName":null,
    "customerRefId":"{{customerRefId}}",
    "note":"",
    "customerExt1":null,
    "customerExt2":null,
    "balance":"0",
    "tokenBalance":null,
    "symbol":"ETH",
    "subjectType":null,
    "tokenSymbol":null,
    "transaction":{
      "to":"TLFNznovqX6FRjk1bkbX47KUGQX2UAaFnY",
      "value":"0",
      "chainId":1,
      "gasPrice":"0",
      "gasLimit":0,
      "maxPriorityFeePerGas":"0",
      "maxFeePerGas":"0",
      "nonce":2,
      "data":"hexData",
      "txHash":null,
      "signedTransaction": "",
      "sig": {
        "hash":"hashString",
        "sig": null
      }
    },
    "message":{
      "chainId":1,
      "data":"json",
      "sig": {
        "hash":"hashString",
        "sig": null
      }
    },
    "messageHash":{
      "chainId":1,
      "sigList":[
        {
          "hash":"hashString",
          "sig": null
        }
      ]
    }
  }
}

Response Data

Parameter Type Description
txKey string Transaction key
accountKey string Source account key
sourceAddress string Source address
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
createdByUserKey string Creator key
createdByUserName string Creator username
createTime int64 Transaction creation time, UNIX timestamp (ms)
auditUserKey string Final approver key
auditUserName string Final approver username
customerRefId string Merchant unique business ID
note string Note
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
balance string Account balance
tokenBalance string Token balance
symbol string Coin unit
tokenSymbol string Token name
subjectType string Signature Type
transaction object This field is returned when the signature type is ETH_SIGNTRANSACTION
└─to string To
└─value string Value
└─chainId int64 Chain ID
└─gasPrice string Gas price
└─gasLimit int32 Gas limit
└─maxPriorityFeePerGas string Max priority fee per gas for EIP-1559
└─maxFeePerGas string Max fee per gas for EIP-1559
└─nonce int64 Nonce
└─data string Data
└─txHash string Transaction hash (This value is returned for signed transactions)
└─signedTransaction string Hexadecimal data (This value is returned for signed transactions)
└─sig object Sign
     └─hash string Hash
     └─sig string Sign (This value is returned for signed transactions)
message object This field is returned when the signature type is PERSONAL_SIGN or ETH_SIGN_TYPED_DATA
└─chainId int64 Chain ID
└─data string Data
└─sig object Sign
     └─hash string Hash
     └─sig string Sign (This value is returned for signed transactions)
messageHash object This field is returned when the signature type is ETH_SIGN
└─chainId int64 Chain ID
└─sigList array Signature list
     └─hash string Hash
     └─sig string Sign (This value is returned for signed transactions)

Web3 Sign Transaction List

Filter Web3 Sign history of the team according to different condition combinations.

HTTP Request

POST /v1/web3/sign/list

Request Parameters

Parameter Type Required Description
direct string No Page query direction, NEXT by default
limit int32 No The amount of items to retrieve at a time, the default max value is 500
fromId string No txKey of the first transaction history. If the txKey of transaction history has no set value, the starting page is the first page by default
subjectType string No Web3 Sign Type
transactionStatus array No Transaction status
accountKey string No Source account key
startTime string No Start time, UNIX time in milliseconds
endTime string No End time, UNIX time in milliseconds

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent":
  [
    {
      "txKey":null,
      "accountKey":null,
      "sourceAddress":null,
      "transactionStatus":null,
      "transactionSubStatus":null,
      "createdByUserKey":null,
      "createdByUserName":null,
      "createTime":null,
      "auditUserKey":null,
      "auditUserName":null,
      "customerRefId":"{{customerRefId}}",
      "note":"",
      "customerExt1":null,
      "customerExt2":null,
      "balance":"0",
      "tokenBalance":null,
      "symbol":"ETH",
      "subjectType":null,
      "tokenSymbol":null,
      "transaction":{
        "to":"TLFNznovqX6FRjk1bkbX47KUGQX2UAaFnY",
        "value":"0",
        "chainId":1,
        "gasPrice":"0",
        "gasLimit":0,
        "maxPriorityFeePerGas":"0",
        "maxFeePerGas":"0",
        "nonce":2,
        "data":"hexData",
        "txHash":null,
        "signedTransaction": "",
        "sig": {
          "hash":"hashString",
          "sig": null
        }
      },
      "message":{
        "chainId":1,
        "data":"json",
        "sig": {
          "hash":"hashString",
          "sig": null
        }
      },
      "messageHash":{
        "chainId":1,
        "sigList":[
          {
            "hash":"hashString",
            "sig": null
          }
        ]
      }
    }
  ]
}

Response Data

Parameter Type Description
txKey string Transaction key
accountKey string Source account key
sourceAddress string Source address
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
createdByUserKey string Creator key
createdByUserName string Creator username
createTime int64 Transaction creation time, UNIX timestamp (ms)
auditUserKey string Final approver key
auditUserName string Final approver username
customerRefId string Merchant unique business ID
note string Note
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
balance string Account balance
tokenBalance string Token balance
symbol string Coin unit
tokenSymbol string Token name
subjectType string Signature Type
transaction object This field is returned when the signature type is ETH_SIGNTRANSACTION
└─to string To
└─value string Value
└─chainId int64 Chain ID
└─gasPrice string Gas price
└─gasLimit int32 Gas limit
└─maxPriorityFeePerGas string Max priority fee per gas for EIP-1559
└─maxFeePerGas string Max fee per gas for EIP-1559
└─nonce int64 Nonce
└─data string Data
└─txHash string Transaction hash (This value is returned for signed transactions)
└─signedTransaction string Hexadecimal data (This value is returned for signed transactions)
└─sig object Sign
     └─hash string Hash
     └─sig string Sign (This value is returned for signed transactions)
message object This field is returned when the signature type is PERSONAL_SIGN or ETH_SIGN_TYPED_DATA
└─chainId int64 Chain ID
└─data string Data
└─sig object Sign
     └─hash string Hash
     └─sig string Sign (This value is returned for signed transactions)
messageHash object This field is returned when the signature type is ETH_SIGN
└─chainId int64 Chain ID
└─sigList array Signature list
     └─hash string Hash
     └─sig string Sign (This value is returned for signed transactions)

MPC Sign

MPC Sign Introduction

Safeheron has opened the MPC-based underlying signature capability, allowing you to flexibly apply the "signable but invisible key" feature of the MPC signature algorithm to your businesses, such as:

Create and sign an ETH transaction as follow to show MPC Sign:

Single private key signing as follow:

  1. Prepare transaction data: from, to, nonce, gasLimit, gasPrice, value, data
  2. Serialize: rawTransaction = RLP(from, to, nonce, gasLimit, gasPrice, value, data)
  3. Compute transaction data hash: hash = sha3(rawTransaction)
  4. Sign transaction data hash by single private key: sig = secp256k1Sign(private key, hash)
  5. Signed transaction data: signedRawTransaction = RLP(from, to, nonce, gasLimit, gasPrice, value, data, sig)
  6. Compute transaction hash: txHash = sha3(signedRawTransaction)
  7. Broadcast transaction: rpc.submitTransaction(signedRawTransaction)

If the above process is automated, the single private key is inevitable to be used in the server which brings in security risks such as private key exposure. To solve security issues faced by single private key, you can use Safeheron MPC Sign to sign in a distributed manner that the original private key will never appear in application memory during signing. Your private key is secure through distributed signing via MPC Sign.

Reformed signing via Safeheron MPC Sign as follow:

  1. [Customer]Prepare transaction data: from, to, nonce, gasLimit, gasPrice, value, data
  2. [Customer]Serialize: rawTransaction = RLP(from, to, nonce, gasLimit, gasPrice, value, data)
  3. [Customer]Compute transaction data hash: hash = sha3(rawTransaction)
  4. [Customer+Safeheron] Sign transaction data hash by single private key: sig = secp256k1Sign(private key, hash)
  5. [Customer] Signed transaction data: signedRawTransaction = RLP(from, to, nonce, gasLimit, gasPrice, value, data, sig)
  6. [Customer]Compute transaction hash: txHash = sha3(signedRawTransaction)
  7. [Customer] Broadcast transaction: rpc.submitTransaction(signedRawTransaction)

Comparing the two signings above, it's worth noticing that in the process of using Safeheron MPC Sign, when signing with the private key, Safeheron MPC Sign is used to sign the hash, and then the signature result is returned. Customer can apply the result to own business logic.
Note: Currently, MPC protocol supports Secp256k1 signature algorithm, and it will support more signature algorithms like Ed25519, BLS and Schnorr.

API

Create a Wallet Account

Create a Wallet Account

Create an MPC Sign Transaction

Merchant can initiate MPC Sign via this interface. Merchant serializes transaction data and generate transaction data hash, then use this interface to submit hash and create signing transaction. Retrieve the signing result through MPC Sign transaction interface or Webhook. Merchant can continue the follow-up process for obtaining signature as per self needs.

HTTP Request

POST /v1/transactions/mpcsign/create

Request Parameters

Parameter Type Required Description
customerRefId string Yes Merchant unique business ID (within 100 characters)
customerExt1 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
customerExt2 string No Merchant extended field (defined by merchant) shown to merchant (within 255 characters)
sourceAccountKey string Yes Source account key
signAlg string Yes Signature algorithm, currently only supports Secp256k1
hashs array Yes Transaction signature hash list
└─note string No Transaction note (within 180 characters)
└─hash string Yes Original signature hash, 32-byte hex string not starting with 0x

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "txKey": "tx46461daa9b7a4612abce99e7ce598844"
  }
}

Response Data

Parameter Type Description
txKey string Transaction key

Retrieve an MPC Sign Transaction

Retrieve a specific MPC Sign transaction. Either customerRefId or txKey is required. If the both have values, then retrieve according to txKey.

HTTP Request

POST /v1/transactions/mpcsign/one

Request Parameters

Parameter Type Required Description
txKey string No Transaction key
customerRefId string No Merchant unique business ID (within 100 characters)

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": {
    "txKey": "tx46461daa9b7a4612abce99e7ce598844",
    "transactionStatus": "COMPLETED",
    "transactionSubStatus": "CONFIRMED",
    "createTime": 1626075236000,
    "sourceAccountKey": "accountbb6acc4892264e8c9202b9cd3e3235a3",
    "auditUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "createdByUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "customerRefId": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "customerExt1": "1",
    "customerExt2": "2",
    "signAlg": "secp256k1",
    "auditUserName": "test",
    "createdByUserName": "test",
    "hashs": [
      {
        "note": "Initiate transaction",
        "hash": "d061e9c5891f579fd548cfd22ff29f5c642714cc7e7a9215f0071ef5a5723f69",
        "sig": "b3d5b45dec592d6ca60455f2926e06e5ff1c81cc4115d44d4b4f9953e6260aee55bc80e341977ab77713c80b31d960be01e09bb19014db49484db45859c77fda00"
      }
    ]
  }
}

Response Data

Parameter Type Description
txKey string Transaction key
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
createTime int64 Transaction creation time, UNIX timestamp (ms)
sourceAccountKey string Source account key
auditUserKey string Final approver key
createdByUserKey string Creator key
customerRefId string Merchant unique business ID
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
signAlg string Signature algorithm
auditUserName string Final approver username
createdByUserName string Creator username
hashs array Transaction signature hash list
└─note string Note
└─hash string Original signature hash, 32-byte hex string not starting with 0x
└─sig string Transaction signature (The value of sig consists of 32 bytes r + 32 bytes s + 1 byte v)

MPC Sign Transaction List

Filter MPC Sign transaction history of the team according to different condition combinations.

HTTP Request

POST /v1/transactions/mpcsign/list

Request Parameters

Parameter Type Required Description
direct string No Page query direction, NEXT by default
limit int32 No The amount of items to retrieve at a time, the default max value is 500
fromId string No txKey of the first transaction history. If the txKey of transaction history has no set value, the starting page is the first page by default
createTimeMin int64 No Start time for creating a transaction, UNIX timestamp (ms)
createTimeMax int64 No End time for creating a transaction, UNIX timestamp (ms)

Example Response

{
  "code": 200,
  "message": "SUCCESS",
  "timestamp": "1626336745267",
  "sig": "ZHIHfOoAH9WMCK2yXg8TkLSrotntBuVzMjTPTKrffpTb1rQlffTrlIFloinflgje/2gkZ8Jj9OPkOt/J1QDbyAkuQCbwu3lVOur83NzPsckFETbhmRHEUKmZYbNXm3abheVA7wx06NA1jtDy0NgUxL/f8WOJn0T3pUBdSj9lmKdeXJ8K2v9JS1wPDjnW0WTGlxviOgAy2rxRio7cj6f/GrVokN2I6itNYF82njOV2WI3P2fVOBPwq0SoRcFnHcH9OjxmXjJWqrhd/N5V5KfSHUORarDtDGOXuknplJ9bhUjN30lF6FDzidZVyeptbUeNK0yeWRoUVmnt+MhsjOHnyA==",
  "key": "y0WmiDSL23d4H5uYgc+F+yopfapj113jZYNK5nEdf7ebETIjb2IWBjaKEIAnbkxE/TJ0C/Y2EUx7D6j8ojuRcji9jnprSvdiRu9po/t08pZ3X9DEV9D6FJEud5xVCdhFLXWynYtmRpo9bGQB840s7Lykc8zM971wEk8vEhDDQeiD6C/JSDPGo6+TuTyKlOdqe9tO2fIX/4FqaYrAe8mC7yOp7oYJqV7oTi5/b8yNI5pgGXhGUqG1QDeDN218vwFctxbae01N3Q1+WgSHO+YhcBIc0bzo8ppSICUSudbY4E0DTRdF89t3df7iL7dd0zB6QWxNjHCKVeu1kmIW7GqLqg==",
  "bizContent": [
    {
      "txKey": "tx46461daa9b7a4612abce99e7ce598844",
      "transactionStatus": "COMPLETED",
      "transactionSubStatus": "CONFIRMED",
      "createTime": 1626075236000,
      "sourceAccountKey": "accountbb6acc4892264e8c9202b9cd3e3235a3",
      "auditUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
      "createdByUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
      "customerRefId": "a1ef6672-c231-43cc-b174-ff30d392e723",
      "customerExt1": "1",
      "customerExt2": "2",
      "signAlg": "secp256k1",
      "auditUserName": "test",
      "createdByUserName": "test",
      "hashs": [
        {
          "note": "Initiate transaction",
          "hash": "d061e9c5891f579fd548cfd22ff29f5c642714cc7e7a9215f0071ef5a5723f69",
          "sig": "b3d5b45dec592d6ca60455f2926e06e5ff1c81cc4115d44d4b4f9953e6260aee55bc80e341977ab77713c80b31d960be01e09bb19014db49484db45859c77fda00"
        }
      ]
    }
  ]
}

Response Data

Parameter Type Description
txKey string Transaction key
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
createTime int64 Transaction creation time, UNIX timestamp (ms)
sourceAccountKey string Source account key
auditUserKey string Final approver key
createdByUserKey string Creator key
customerRefId string Merchant unique business ID
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
signAlg string Signature algorithm
auditUserName string Final approver username
createdByUserName string Creator username
hashs array Transaction signature hash list
└─note string Note
└─hash string Original signature hash, 32-byte hex string not starting with 0x
└─sig string Transaction signature (The value of sig consists of 32 bytes r + 32 bytes s + 1 byte v)

Webhook

Webhook Overview

Through Webhook, Safeheron will push some event notifications about your team. Such as:

If you need event notifications, you can use the user account (with Manage API permission) to log into Safeheron Console, in Settings-> API Account Management to configure Webhook.

When Webhook does callback, it will adopt the same data encryption & signature scheme as in API Authentication that you need to configure your Webhook RSA public key on Safeheron Console. You can generate an RSA public-private key pair referring to API Authentication. You can obtain Safeheron Webhook RSA public key on Safeheron Console, and use this public key to verify the signature of the callback data.

Callback Request

Safeheron sends a POST request to the Webhook callback address you set in the Console, Content-Type in the HTTP request header is application/json;charset=UTF-8.

Callback Request Parameters

Example Callback Request

{
    "bizContent": "string",
    "sig": "string",
    "key": "string",
    "timestamp":"string"
}
Parameter Type Description
timestamp string Callback timestamp, UNIX millisecond-format string
bizContent string AES-encrypted data of request parameters
sig string Signature data from Safeheron Webhook RSA private key signing request parameters
key string Encrypted data of random AES key by Webhook RSA public key

You can decrypt callback data and verify its signature as follow:

After receiving Webhook push notification, you need to return successful (HTTP status code 200) response. The content format in successful response is fixed as:

Example Webhook Response

{
  "code":200,
  "message":"SUCCESS"
}

Example shown on the right:

Parameter Type Description
code string Webhook response code, success is fixed at 200
message string Returned information from Webhook, successful is fixed as SUCCESS

Safeheron will regard this push notification failed with receiving status codes other than 200 status code and response content in the above formats. And, Safeheron will resend the notification in the frequency of 30s, 1m, 5m, 1h, 12h, 24h.

Event Format

Decrypted data format of bizContent field as shown in the right:

Example Event Format

{
    "eventType": "TRANSACTION_CREATED",
    "eventDetail": {
    }
}
Parameter Type Description
eventType string Callback event type
eventDetail object Callback event details

Event Type

eventType eventDetail Description
TRANSACTION_CREATED TransactionParam Create a Transaction
TRANSACTION_STATUS_CHANGED TransactionParam Change the transaction status
MPC_SIGN_CREATED MPCSignParam Create an MPC Sign Transaction
MPC_SIGN_STATUS_CHANGED MPCSignParam Change the MPC Sign transaction status
WEB3_SIGN_CREATED Web3SignParam Create a Web3 Sign Transaction
WEB3_SIGN_STATUS_CHANGED Web3SignParam Change the Web3 Sign transaction status

Event Details

TransactionParam

Example TransactionParam

{
    "txKey": "tx46461daa9b7a4612abce99e7ce598844",
    "txHash": "0xf7292ea446b573bab7311921e2489fb29d26ec393f2d6c8e280a7157f635234",
    "coinKey": "ETH_ROPSTEN",
    "txAmount": "0.001",
    "sourceAccountKey": "account4b8d2c00520646c8862b68420aa1234234",
    "sourceAccountType": "VAULT_ACCOUNT",
    "sourceAddress": "0xCa104eA8CB4722e33a3E68eD4D12d3569594FBC5",
    "destinationAccountKey": "6553009588f443b1970a5962590a2158",
    "destinationAccountType": "WHITELISTING_ACCOUNT",
    "destinationAddress": "0xCa104eA8CB4722e33a3E68eD4D12d3569594F234234",
    "destinationTag": "TEST",
    "transactionStatus": "COMPLETED",
    "transactionSubStatus": "CONFIRMED",
    "createTime": 1626075236000,
    "note": "Initiate transaction",
    "auditUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "createdByUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "txFee": "0.000106841386050000",
    "feeCoinKey": "ETH_ROPSTEN",
    "replaceTxHash": "0x628626531285bb90d4130d3beb3c355d2a7fe0bdfa1fa05e3431f15340aafeb6",
    "customerRefId": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "customerExt1": "1",
    "customerExt2": "2",
    "amlLock": "NO",
    "blockHeight": 10000000,
    "completedTime": 1626075236000,
    "realDestinationAccountType": "VAULT_ACCOUNT"
  }
Parameter Type Description
txKey string Transaction key
txHash string Transaction hash
coinKey string Coin key
txAmount string Transaction amount, the unit is the symbol returned by the coin list
sourceAccountKey string Source account key
sourceAccountType string Source account type
sourceAddress string Source address
destinationAccountKey string Destination account key
destinationAccountType string Destination account type
destinationAddress string Destination address
destinationTag string If the destination is tag or memo type, then this value is empty
transactionStatus string Transaction status. When the status is confirming, as the block confirmations reach the set amount, the transaction status to be updated into success
transactionSubStatus string Transaction substatus
createTime int64 Transaction creation time, UNIX timestamp (ms)
note string Note
auditUserKey string Final approver key
createdByUserKey string Creator key
txFee string Transaction fee
feeCoinKey string Coin key of consumed transaction fee for transfer, eg. transfer ERC-20 token, then the consumed transaction fee is ETH.
replaceTxHash string Quoted transaction hash (only for the sped-up transaction)
customerRefId string Merchant unique business ID
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen
blockHeight int64 Block height (for confirming transaction and succeeded transaction)
completedTime int64 Transaction completion time
realDestinationAccountType string Type of actual destination account

MPCSignParam

Example MPCSignParam

{
    "txKey": "tx697eebea3a61440a8edf6f0a783d19b2",
    "sourceAccountKey": "sourceAccountKey",
    "auditUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "createdByUserKey": "a1ef6672-c231-43cc-b174-ff30d392e723",
    "createTime": 1626075236000,
    "customerRefId": "1639558034534",
    "customerExt1": "",
    "customerExt2": "",
    "signAlg": "secp256k1",
    "transactionStatus": "CANCELLED",
    "transactionSubStatus": "",
    "hashs": [
        {
            "note": "",
            "hash": "d061e9c5891f579fd548cfd22ff29f5c642714cc7e7a9215f0071ef5a5723f69",
            "sig":""
        }
    ]
}
Parameter Type Description
txKey string Transaction key
signAlg string Signature algorithm, currently supports secp256k1
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
sourceAccountKey string Source account key
auditUserKey string Final approver key
createdByUserKey string Creator key
createTime int64 Transaction creation time, UNIX timestamp (ms)
customerRefId string Custom unique business identifier. When creating a transaction, Safeheron uses this field for idempotent request
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
hashs array Source account information for transaction signatures
└─note string Transaction note
└─hash string Signature hash
└─sig string Transaction signature (The value of sig consists of 32 bytes r + 32 bytes s + 1 byte v)

Web3SignParam

Example Web3SignParam

  {
  "txKey":null,
  "subjectType":null,
  "accountKey":null,
  "sourceAccountType":null,
  "sourceAddress":null,
  "transactionStatus":null,
  "transactionSubStatus":null,
  "createdByUserKey":null,
  "createTime":null,
  "auditUserKey":null,
  "note":"",
  "customerExt1":null,
  "customerExt2":null,
  "transaction":{
    "to":"TLFNznovqX6FRjk1bkbX47KUGQX2UAaFnY",
    "value":"0",
    "chainId":1,
    "gasPrice":"0",
    "gasLimit":0,
    "maxPriorityFeePerGas":"0",
    "maxFeePerGas":"0",
    "nonce":2,
    "data":"hexData",
    "txHash":null,
    "signedTransaction": "",
    "sig": {
      "hash":"hashString",
      "sig": null
    }
  },
  "message":{
    "chainId":1,
    "data":"json",
    "sig": {
      "hash":"hashString",
      "sig": null
    }
  },
  "messageHash":{
    "chainId":1,
    "sigList":[
      {
        "hash":"hashString",
        "sig": null
      }
    ]
  }
}
Parameter Type Description
txKey string Transaction key
subjectType string Signature Type
accountKey string Source account key
sourceAccountType string Source account type
sourceAddress string Source address
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
createdByUserKey string Creator key
createTime int64 Transaction creation time, UNIX timestamp (ms)
auditUserKey string Final approver key
note string Note
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
transaction object This field is returned when the signature type is ETH_SIGNTRANSACTION
└─to string to
└─value string value
└─chainId int64 Chain ID
└─gasPrice string gasPrice
└─gasLimit int32 gasLimit
└─maxPriorityFeePerGas string EIP-1559 maxPriorityFeePerGas
└─maxFeePerGas string EIP-1559 maxFeePerGas
└─nonce int64 nonce
└─data string data
└─txHash string Transaction hash (This value is returned for signed transactions)
└─signedTransaction string Hexadecimal data (This value is returned for signed transactions)
└─sig object Sign
     └─hash string hash
     └─sig string Sign (This value is returned for signed transactions)
message object This field is returned when the signature type is PERSONAL_SIGN or ETH_SIGN_TYPED_DATA
└─chainId int64 Chain ID
└─data string data
└─sig object Sign
     └─hash string hash
     └─sig string Sign (This value is returned for signed transactions)
messageHash object This field is returned when the signature type is ETH_SIGN
└─chainId int64 Chain ID
└─sigList array sigList
     └─hash string hash
     └─sig string Sign (This value is returned for signed transactions)

Supported Coins

Coin Coin's Block Confirmations Account type
Ethereum 12 ACCOUNT
Ethereum(Ropsten) 50 ACCOUNT
Bsc 12 ACCOUNT
Heco 12 ACCOUNT
Tron 20 ACCOUNT
Avalanche 120 ACCOUNT
Ether Classic 500 ACCOUNT
Bitcoin 2 UTXO
Bitcoin cash 10 UTXO
Dash 10 UTXO

API Co-Signer

API Co-Signer Overview

API Co-Signer is for automating singing process which is privately deployed by you. API Co-Signer contains authorization of private key (for authorizing transactions) and MPC private key shards (for MPC signing).

API Co-Signer will have transaction approval task callback your business system and then reject or approve the transaction approval according to your business system response. Automated signing as follow:

Automated signing

Co-Signer Callback

API Co-Signer will send a POST request to the configured callback address. The Content-Type in HTTP request header is application/json;charset=UTF-8.

When API Co-Signer does callback, it will adopt the same data encryption & signature scheme as in API Authentication that you need to configure your Callback RSA public key on API Co-Signer. You can generate an RSA public-private key pair referring to API Authentication. You can obtain Safeheron Webhook RSA public key on Safeheron Console, and use this public key to verify the signature of the callback data.

When configure API Co-Signer, you need to configure API RSA public-private key pair to communicate with Safeheron API gateway. During callback of your business system by API Co-Signer, API RSA public-private key pair will be readopted to communicate with your business system.

Callback Request

Callback request parameters as follow:

Example Callback Request

{
    "bizContent": "string",
    "sig": "string",
    "key": "string",
    "timestamp":"string"
}
Parameter Type Description
timestamp string Callback timestamp
bizContent string AES-encrypted data of request parameters
sig string Signature data after signing request parameters by your API RSA Private Key
key string Encrypted data of random AES key by Callback RSA public key

You can decrypt callback data and verify its signature as follow:

Callback Response

Callback response parameters as follow:

Example Callback Response

{
    "code": 200,
    "message": "SUCCESS",
    "timestamp": "1628652100447",
    "bizContent": "string",
    "key": "string",
    "sig": "string"
}
Parameter Type Description
code int Response result code for log output, use 200 for normal return
message string Response result description for log output, use SUCCESS for normal return
timestamp string Response timestamp
sig string Signature data after signing response parameters by your Callback RSA Private Key
key string Encrypted data of random AES key by your API RSA Public Key
bizContent object AES-encrypted data of response parameters

You can decrypt response data and verify its signature as follow:

Co-Signer Business Callback Dictionary

Callback Dictionary

Parameter Type Description
type string Business Type
customerContent object Business content

Callback Type

type customerContent Description
TRANSACTION Transaction approval Approve transactions
MPC_SIGN MPC Sign approval Sign transactions
Web3_SIGN Web3 Sign approval Sign transactions

Transaction Approval

Example

{
    "auditRecordKey": "57e3a3e0eb3140c3ba538cc094bcb024",
    "txKey": "txc0710da7db2b42ff9bf28df8910f8a88",
    "coinKey": "ETH_ROPSTEN",
    "txAmount": "0.012000000000000000",
    "sourceAddress":"0xCa104eA8CB4722e33a3E68eD4D12d3569594FBC5",
    "sourceAccountKey": "accounta5867fecbbbc4a4f876532c87477407a",
    "sourceAccountType": "VAULT_ACCOUNT",
    "destinationAccountKey": "0259e8c481c345ca922f489961bc331b",
    "destinationAccountType": "INTERNAL_WALLET",
    "destinationAddress": "0xCa104eA8CB4722e33a3E68eD4D12d3569594FBC5",
    "destinationTag": null,
    "customerRefId": "123234111112112",
    "triggerTime": 1635938498071,
        "triggerUserName": "signer",
    "txHash": "",
    "blockHeight": null,
    "feeCoinKey": "ETH_ROPSTEN",
    "fee": null,
    "amlLock": "NO",
    "customerExt1": "",
    "customerExt1": ""
}
Parameter Type Description
txKey string Transaction key
txHash string Transaction hash
coinKey string Coin key
txAmount string Transaction amount, the unit is the symbol returned by the coin list
sourceAccountKey string Source account key
sourceAccountType string Source account type
sourceAddress string Source address
destinationAccountKey string Destination account key
destinationAccountType string Destination account type
destinationAddress string Destination address
destinationTag string If the destination is tag or memo type, then this value is empty
vaultTxDirection string Transaction Direction
transactionStatus string Transaction status. When the status is confirming, as the block confirmations reach the set amount, the transaction status to be updated into success
transactionSubStatus string Transaction substatus
createTime int64 Transaction creation time, UNIX timestamp (ms)
note string Note
auditUserKey string Final approver key
createdByUserKey string Creator key
txFee string Transaction fee
feeCoinKey string Coin key of consumed transaction fee for transfer, eg. transfer ERC-20 token, then the consumed transaction fee is ETH.
replaceTxHash string Quoted transaction hash (only for the sped-up transaction)
customerRefId string Merchant unique business ID
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
amlLock string Whether frozen by AML
YES: frozen
NO: unfrozen

MPC Sign Approval

Example

{
    "auditRecordKey": "57e3a3e0eb3140c3ba538cc094bcb024",
    "txKey": "tx697eebea3a61440a8edf6f0a783d19b2",
    "triggerTime": 1635938498071,
        "triggerUserName": "signer",
    "note": "",
    "customerRefId": "1639558034534",
    "customerExt1": "",
    "customerExt2": "",
    "signAlg": "secp256k1",
    "hashs": [
        {
            "sourceAccountKey": "sourceAccountKey",
            "hash": "d061e9c5891f579fd548cfd22ff29f5c642714cc7e7a9215f0071ef5a5723f69"
        }
    ]
}
Parameter Type Description
auditRecordKey string Approval history unique identifier
customerRefId string Merchant unique business ID
note string Transaction note
triggerTime string Approval triggered time
triggerUserName string Approval trigger name
txKey string Transaction unique ID key
customerExt1 string Merchant extended field
customerExt2 string Merchant extended field
signAlg string Signature algorithm
hashs array Source account information for transaction signatures
└─sourceAccountKey string Source account key
└─hash string Signature hash

Web3 Sign Approval

Example

  {
  "txKey":null,
  "subjectType":null,
  "accountKey":null,
  "sourceAddress":null,
  "transactionStatus":null,
  "transactionSubStatus":null,
  "createdByUserKey":null,
  "createTime":null,
  "auditUserKey":null,
  "customerRefId":"",
  "transaction":{
    "to":"TLFNznovqX6FRjk1bkbX47KUGQX2UAaFnY",
    "value":"0",
    "chainId":1,
    "gasPrice":"0",
    "gasLimit":0,
    "maxPriorityFeePerGas":"0",
    "maxFeePerGas":"0",
    "nonce":2,
    "data":"hexData",
    "txHash":null
  },
  "message":{
    "chainId":1,
    "data":"json"
  },
  "messageHash":{
    "chainId":1,
    "data":[""]
  }
}
Parameter Type Description
txKey string Transaction key
subjectType string Signature Type
accountKey string Source account key
sourceAddress string Source address
transactionStatus string Transaction status
transactionSubStatus string Transaction substatus
createdByUserKey string Creator key
createTime int64 Transaction creation time, UNIX timestamp (ms)
auditUserKey string Final approver key
customerRefId string Merchant unique business ID
transaction object This field is returned when the signature type is ETH_SIGNTRANSACTION
└─to string to
└─value string value
└─chainId int64 Chain ID
└─gasPrice string gasPrice
└─gasLimit int32 gasLimit
└─maxPriorityFeePerGas string EIP-1559 maxPriorityFeePerGas
└─maxFeePerGas string EIP-1559 maxFeePerGas
└─nonce int64 nonce
└─data string data
└─txHash string Transaction hash
message object This field is returned when the signature type is PERSONAL_SIGN or ETH_SIGN_TYPED_DATA
└─chainId int64 Chain ID
└─data string data
messageHash object This field is returned when the signature type is ETH_SIGN
└─chainId int64 Chain ID
└─data array Hash to be signed

Response Dictionary

Transaction Approval Task

Parameter Type Required Description
approve boolean Yes Approval result:
True: approved
False: rejected

Error Code

Error Code Description
200 Success
500 System error
1001 Unknown exception, please contact Safeheron Support
1004 Duplicate request
1005 User doesn't have permission
1008 Invalid request
1009 Invalid API key
1010 Parameter decryption failed
1011 Invalid IP
1012 Signature verification failed
1013 Timestamp check failed
1014 IP exceeds frequency limit
1015 Invalid user state
1016 Invalid API Key state
1017 Parameter validation error
1018 Request record doesn't exist
3009 Frozen merchant
3010 Closed merchant
3016 Failed to request basic service
3017 The wallet is disabled
3018 Illegal merchant status
3019 Insufficient funds to meet withdrawal requests
3020 Non-review status, this operation cannot be performed
3021 Request transaction result exception
3022 Request transaction failed
3023 The current wallet does not allow this operation
3024 Transaction package data verification failed
3025 Signing failed
3026 Record cancelled
3027 Audit record has been processed
3028 The current wallet does not allow this operation
3029 The hash entered is illegal
3030 The network corresponding to chainId does not exist
3031 Hash temporarily supports 1 incoming
3032 Data cannot be empty
3033 ChainId cannot be empty
3034 Illegal data format
3035 Data length must be between 0 and 100000
3036 Value cannot be empty
3037 Nonce cannot be empty
3038 Value is illegal
3039 GasPrice is illegal
3040 GasLimit too large
3041 MaxPriorityFeePerGas is illegal
3042 MaxFeePerGas is illegal
3043 GasLimit cannot be empty
3044 MaxPriorityFeePerGas is less than the current value of the network
3045 MaxFee too low
3046 GasPrice and feePerGas cannot be null at the same time
3047 Data length must be between 0 and 1000000
3048 Nonce too low
3049 Nonce too high
3050 The utxo type does not support skipping balance check
3051 Asset is not supported
3052 Version cannot be empty
3053 Version error
3054 Accelerated coin are not supported
3055 Please backup private key before create asset
3056 FeeRate must be greater than 0
3057 GasLimit must be greater than 0
3058 MaxPriorityFee must be greater than 0
3059 MaxFee must be greater than 0
9001 Merchant unique business ID already exists
9002 System under maintenance, transfer suspended
9003 Sent amount has wrong decimal
9004 Wrong fee rate decimal
9005 Hidden account cannot change name
9006 Hidden account cannot withdraw coins
9007 Frozen source account
9008 Address already exists
9009 Wrong address format
9010 Security risks from deposit address
9011 Address book already has this coin
9012 Address doesn't exist
9013 Invalid whitelisted address state
9015 Frozen destination account
9016 Security risks from this transfer address. Please be cautious for your asset security. Contact Safeheron Support if you have any problem
9017 Insufficient transaction fee
9018 Transaction fee too high
9019 Transaction fee too low
9020 Source address and destination address cannot be the same for TRX coins
9021 The transaction to be replaced doesn't exist
9022 Only broadcasting transaction can be sped up
9023 This coin doesn't support speed-up
9024 Unauthorized user tries to create or approve a transaction
9025 The withdrawal amount is below the minimum limit
9026 Insufficient amount for withdrawal
9027 The policy is matched, but the approver is not the approval role
9028 No matching transaction policy
9030 Non-cancellable status
9031 The estimated online transaction fee is greater than the max transaction fee
9032 Non-UTXO coin
9033 Whitelisted address name already exists
9034 Address and ID are not matched
9035 Transaction history doesn't exist
9036 Source account doesn't exist
9037 Account coin doesn't exist
9038 The coin is not supported yet
9039 The number of wallet accounts exceeds the limit
9040 The number of addresses exceeds the limit
9041 Wallet name already exists
9042 Do not meet UTXO-based fund sweeping requirements
9043 MPC Sign currently only supports one same account
9044 Invalid hash
9045 Another address book already has this address
9046 Transaction number does not exist
9047 Gaslimit is less than the minimum value
9048 Abnormal risk control detection
9049 Address Contract error
9050 Grammatical errors
9051 Please wait patiently during the broadcast
9052 The transaction output has been used and cannot be accelerated
9053 The accelerated transaction has been linked or nonce has been occupied
9054 The whitelist address must be in the approved status to allow transfer
9055 Insufficient UTXO
9056 Acceleration cannot be repeated
9057 The rate of RBF accelerated transaction shall be higher than that of the accelerated transaction

Data Dictionary

Transaction status

Dictionary Code Description
SUBMITTED Pending authorization
SIGNING Signing
CANCELLED Transaction cancelled
BROADCASTING Broadcasting
CONFIRMING Confirming
COMPLETED Transaction succeeded
FAILED Transaction failed
REJECTED Reject

Transaction Substatus

Dictionary Code Description
CONFIRMED Confirmed
UN_KNOW_ERROR Unexpected error
REVIEW_REJECTED Rejected
TRADING_STRATEGY_BLOCKING Transaction policy blocks
MATCHING_RULE_NO_AUDITOR The policy is matched, but the editor is not the approval role
TX_INFO_ERROR Failed to transact
NONCE_TOO_LOW Nonce too low
INTRINSIC_GAS_TOO_LOW Gas limit too low, cannot perform transaction
INSUFFICIENT_FUNDS Insufficient amount for withdrawal
AMOUNT_TOO_SMALL The withdrawal amount is below the minimum limit
TRANSACTION_UNDERPRICED Transaction fee too low that transaction is rejected by node
MISSING_INPUTS Invalid input
INVALID_SIGNATURE Invalid transaction signature
INTERNAL_ERROR An internal error occurred while processing the transaction
TIMEOUT The transaction request timed out
PENDING_BLOCKCHAIN_CONFIRMATIONS Pending blockchain confirmation
TAPOS_ERROR Tapos check error
NODE_SERVER_BUSY Node service is busy
DUP_TRANSACTION_ERROR The transaction is on the chain and the same transaction is resubmitted
TRANSACTION_EXPIRATION_ERROR Transaction timed out
TRANSACTION_EXECUTION_FAILED Transaction execution failed
BANDWITH_ERROR Insufficient account bandwidth points and energy. Increase fee limit or get more bandwith points and energy for transaction
ACCOUNT_DOES_NOT_EXIST Account doesn't exist
NO_MATCHING_RULE_FOUND Transaction failed, configure transaction policy first
WHITELIST_ADDRESS_STATUS_ILLEGAL The address status of the white list is not approved
AML_SCREENING_REJECTED Rejected by AML check
CONTRACT_VALIDATE_ERROR Transaction check error
THE_DEAL_WAS_ABANDONED Transaction abandoned
MANUAL_TX_FAIL Manual processing
CANCELLED_BY_USER User cancelled transaction
RISK_CHECK_ILLEGAL Abnormal risk control detection
WALLET_NOT_ALLOWED The wallet doesn't support current operation
USER_NO_PERMISSION User has no permission
PROCESSING_EXCHANGE Exchange is processing
PENDING_EXCHANGE Pending exchange confirmation
CANCELED_EXCHANGE Exchange cancelled transaction
FAILED_EXCHANGE Exchange transaction failed
CONFIRMING_EXCHANGE Exchange transaction confirming
CONFIRMED_EXCHANGE Exchange transaction confirmed
EXCHANGE_CALL_ERROR Abnormal call to the exchange service
EXCHANGE_SIGNATURE_ERROR Exchange failed to sign
EXCHANGE_WHILELIST_UNSET_ERROR Withdrawal address is not set in the exchange
EXCHANGE_EMAIL_CONFIRMING Pending email confirmation
EXCHANGE_UN_KNOW_ERROR Unexpected error
EXCHANGE_ADDRESS_ERROR Exchange wrong address error
EXCHANGE_IP_ERROR Exchange IP address error
EXCHANGE_INVALID_API Invalid Exchange API account
EXCHANGE_TRANS_PERMISSION_DENIED No withdrawal permission for exchange API
EXCHANGE_INVALID_INFO Invalid API private key, IP or operation permission
EXCHANGE_TRANS_LIMIT Exchange restricts this account's transfer
EXCHANGE_AMOUNT_OVER_LIMIT The transfer amount exceeds the maximum
EXCHANGE_BALANCE_LACK Insufficient balance

Web3 Transaction status

Dictionary Code Description
SUBMITTED Pending authorization
SIGNING Signing
CANCELLED Transaction cancelled
SIGN_COMPLETED MPC successfully signed
FAILED Transaction failed
REJECTED Reject

Transaction Fee Rate Grade

Dictionary Code Description
LOW Low
MIDDLE Medium
HIGH High

Account type

Dictionary Code Description
VAULT_ACCOUNT Vault account

Transaction Source Account Type

Dictionary Code Description
VAULT_ACCOUNT Vault account
UNKNOWN External account

Transaction Destination Account Type

Dictionary Code Description
VAULT_ACCOUNT Vault account
WHITELISTING_ACCOUNT Whitelisted account
ONE_TIME_ADDRESS Unknown address account

Coin's Whitelist Status

Dictionary Code Description
VERIFY_PENDING Approving
VERIFY_PASS Approved
VERIFY_REFUSE Rejected
AML_REFUSE Rejected by risk control

Transaction Direction

Dictionary Code Description
RECEIVE Receive, the source account is external account and the destination account is platform account
SEND Send, the source account is vault account
SEND_SELF Send to self, the source account and the destination account are vault accounts

Coin Type

Dictionary Code Description
NATIVE Native token, such as ETH, BTC
ERC20 Token standard on ETH
OMNI Token standard on BTC
TRC20 Token standard on TRON
BEP20 Token standard on BSC

Token standard on BSC

Dictionary Code Description
DEFAULT Normal address
P2PKH Normal address
P2WPKH SegWit address
P2PKH_CASH BCH-format normal address

Transaction Type

Dictionary Code Description
TRANSACTION Transaction
MPC_SIGN Native signature

Web3 Sign Type

Dictionary Code Description
ETH_SIGN ethSign
PERSONAL_SIGN personalSign
ETH_SIGN_TYPED_DATA ethSignTypedData
ETH_SIGNTRANSACTION ethSignTransaction

Native signature

Dictionary Code Description
secp256k1 secp256k1

Page Query Direction

Dictionary Code Description
PREV Previous
NEXT Next

Balance Verification

Dictionary Code Description
BALANCE_CHECK Verify the balance
NON_CHECK Do not verify the balance

EthSignTypedData Version

Dictionary Code Description
ETH_SIGNTYPEDDATA_V1 eth_signTypedData_v1
ETH_SIGNTYPEDDATA_V3 eth_signTypedData_v3
ETH_SIGNTYPEDDATA_V4 eth_signTypedData_v4

API SDK

We have API SDKs in four languages: Java, js, Golang & Python

Changelog

2022-11-24 v2.1.2

2022-11-03 v2.1.1

2022-09-27 v2.1.0

2022-06-30 v2.0.0

2022-06-18 v1.0.4

2022-01-18 v1.0.3

2021-12-03 v1.0.2

2021-11-17 v1.0.1

2021-08-31 v1.0.0