Key Management System

Key Management System (KMS) is a comprehensive solution for building custodial applications. KMS runs locally on your server and provides security for generating wallets, addresses, and private keys, and for signing transactions.

KMS builds a list of pending transaction to sign and provides the options to complete a transaction after it has been signed and to obtain transaction details with the result of the blockchain operation via the transaction ID.

In KMS, each managed wallet or private key is assigned a unique signature ID (signatureId) that represents that wallet or private key. This signature ID is then used in an API request to identify the wallet.

Depending on the API, you can use the signature ID in an API call request in the following ways:

To represent the mnemonic type of the wallet; for example, in the API for sending BTC from a virtual account to the blockchain (see the transferBtcKMS request schema).
To represent the privateKey type of the wallet; for example, in the API for sending BTC to a blockchain address (see the BtcTransactionFromUTXOKMS request schema).
To represent the mnemonic and index type of the wallet; for example, in the API for sending ETH from a virtual account to the blockchain (see the transferEthKMS request schema).
In this case, the index of the specific private key generated from the mnemonic must be used in addition to the signature ID.

You can run KMS on the following operating systems:

macOS: Natively or via Docker
Unix: Natively or via Docker
MS Windows: Only via Docker

For more information about KMS, see the KMS GitHub repository and the user documentation.

Get pending transactions to sign

1 credit per API call

Get the list of pending transactions to sign and broadcast using KMS.

SecurityX-API-Key

Request

path Parameters

chain

required

string = 24 characters

Blockchain to get pending transactions for.

Enum: "BNB" "BTC" "ETH" "XLM" "XRP" "BCH" "LTC" "DOGE" "VET" "BSC" "MATIC" "CELO" "FLOW" "TRON" "ONE" "XDC" "EGLD" "KLAY" "SOL"

query Parameters

signatures

string

Signature IDs of the KMS which invokes this endpoint. If multiple, they should be separated by comma.

Example: signatures=6d78dad2-518f-4e76-8255-8f1df0de6884,6d78dad2-518f-4e76-8255-8f1df0de6885,6d78dad2-518f-4e76-8255-8f1df0de6886

Responses

200

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/kms/pending/{chain}

Request samples

Response samples

application/json

[{"id": "5e6645712b55823de7ea82f1",
"chain": "ETH",
"hashes": ["1234987askdjfb1o2873ryskajfb1234987askdjfb1o2873ryskajfb1234987askdjfb1o2873ryskajfb"
],
"serializedTransaction": "alskdjfq8o27fbkasljfbq8o7b4fqo83f7bqejhafbo8q4f",
"withdrawalId": "5e6645712b55823de7ea82f1",
"index": 1,
"txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
"withdrawalResponses": [{"address": {"address": "7c21ed165e294db78b95f0f181086d6f",
"currency": "BTC",
"derivationKey": 2147483647,
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka",
"destinationTag": 5,
"memo": "5",
"message": "5"
},
"amount": 0,
"vIn": "string",
"vInIndex": 0,
"scriptPubKey": "string"
}
]
}
]

Get pending transactions to sign

1 credit for every 500 signature IDs per API call

Get the list of pending transactions to sign and broadcast using KMS.

NOTE: This API works only in KMS v5.0 or later. If you use KMS older than v5.0, use this API instead.

SecurityX-API-Key

Request

path Parameters

chain

required

string = 24 characters

Blockchain to get pending transactions for.

Enum: "BNB" "BTC" "ETH" "XLM" "XRP" "BCH" "LTC" "DOGE" "VET" "BSC" "MATIC" "CELO" "FLOW" "TRON" "ONE" "XDC" "EGLD" "KLAY" "SOL"

Request Body schema: application/json

Signature IDs of the KMS which invokes this endpoint.

signatureIds

Array of strings <uuid>

List of the signature Ids to be used to sign transactions.

Responses

200

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

post/v3/kms/pending/{chain}

Request samples

application/json

{ }

Response samples

application/json

[{"id": "5e6645712b55823de7ea82f1",
"chain": "ETH",
"hashes": ["1234987askdjfb1o2873ryskajfb1234987askdjfb1o2873ryskajfb1234987askdjfb1o2873ryskajfb"
],
"serializedTransaction": "alskdjfq8o27fbkasljfbq8o7b4fqo83f7bqejhafbo8q4f",
"withdrawalId": "5e6645712b55823de7ea82f1",
"index": 1,
"txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
"withdrawalResponses": [{"address": {"address": "7c21ed165e294db78b95f0f181086d6f",
"currency": "BTC",
"derivationKey": 2147483647,
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka",
"destinationTag": 5,
"memo": "5",
"message": "5"
},
"amount": 0,
"vIn": "string",
"vInIndex": 0,
"scriptPubKey": "string"
}
]
}
]

Complete pending transaction to sign

2 credits per API call.

Mark pending transaction to sign as a complete and update it with a transactionID from the blockchain.

SecurityX-API-Key

Request

path Parameters

id required	string = 24 characters ID of pending transaction Example: f91827364f91827364ajdur7
txId required	string [ 10 .. 80 ] characters transaction ID of blockchain transaction Example: 0x94Ce79B9F001E25BBEbE7C01998A78F7B27D1326

Responses

204

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

put/v3/kms/{id}/{txId}

Request samples

Response samples

application/json

{"errorCode": "validation.failed",
"message": "Request validation failed. Please see data for additional information.",
"statusCode": 400,
"data": [{"target": {"property": 12345
},
"value": 12345,
"property": "property1",
"constraints": {"min": "property1 must not be less than 50000"
}
}
]
}

Get transaction details

1 credit per API call.

Get detail of transaction to be signed / that was already signed and contains transactionId.

SecurityX-API-Key

Request

path Parameters

required

string = 24 characters

ID of transaction

Responses

200

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

get/v3/kms/{id}

Request samples

Response samples

application/json

{"id": "5e6645712b55823de7ea82f1",
"chain": "ETH",
"hashes": ["1234987askdjfb1o2873ryskajfb1234987askdjfb1o2873ryskajfb1234987askdjfb1o2873ryskajfb"
],
"serializedTransaction": "alskdjfq8o27fbkasljfbq8o7b4fqo83f7bqejhafbo8q4f",
"withdrawalId": "5e6645712b55823de7ea82f1",
"index": 1,
"txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
"withdrawalResponses": [{"address": {"address": "7c21ed165e294db78b95f0f181086d6f",
"currency": "BTC",
"derivationKey": 2147483647,
"xpub": "xpub6FB4LJzdKNkkpsjggFAGS2p34G48pqjtmSktmK2Ke3k1LKqm9ULsg8bGfDakYUrdhe2EHw5uGKX9DrMbrgYnVfDwrksT4ZVQ3vmgEruo3Ka",
"destinationTag": 5,
"memo": "5",
"message": "5"
},
"amount": 0,
"vIn": "string",
"vInIndex": 0,
"scriptPubKey": "string"
}
]
}

Delete transaction

2 credits per API call.

Delete transaction to be signed. When deleting offchain transaction, linked withdrawal will be cancelled automatically.

SecurityX-API-Key

Request

path Parameters

required

string = 24 characters

ID of transaction

query Parameters

revert

boolean

Default: true

Defines whether fee should be reverted to account balance as well as amount. Defaults to true. Revert true would be typically used when withdrawal was not broadcast to blockchain. False is used usually for Ethereum ERC20 based currencies.

Example: revert=true

Responses

204

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

delete/v3/kms/{id}

Request samples

Response samples

application/json

{"errorCode": "validation.failed",
"message": "Request validation failed. Please see data for additional information.",
"statusCode": 400,
"data": [{"target": {"property": 12345
},
"value": 12345,
"property": "property1",
"constraints": {"min": "property1 must not be less than 50000"
}
}
]
}

➔ Next to Malicious address