HexTrust - Wallet Custody Integration

The hextrust plugin connects your exchange to Hex Trust wallet custody, so your users' crypto is held with your own Hex Trust account instead of the built-in HollaEx wallet. It creates deposit addresses in a Hex Trust vault for each user, credits deposits that Hex Trust reports, and sends withdrawals to Hex Trust.

Running your own custody changes how your exchange works. Read Custody options and Custody of exchange funds first.

What you need

• The Enterprise plan on HollaEx Cloud.
• An isolated exchange, outside the public HollaEx Network. You can't switch this yourself. Open a ticket and HollaEx will migrate your exchange. Being isolated means you lose HollaEx Network liquidity.
• Your own Hex Trust account. From your Hex Trust environment you need the API URL, your enterprise ID, an API key, the ES256 private key for signing requests, the Ed25519 webhook public key, and the address withdrawals are sent from.

Set it up

1. Get your Hex Trust details listed above.

2. Install the plugin. Go to Operator Controls → Exchange → Plugins, find hextrust under Available to install and click Install.

3. Configure it. Open the plugin with Configure, fill in the settings and save. The plugin doesn't start until every setting is filled in.

   Setting	What it does
   api_url	Hex Trust's API address. The default, https://api.sandbox.hexsafe.hextrust.com, is the sandbox. For live funds, use the production address Hex Trust gives you.
   enterprise_id	Your Hex Trust enterprise ID.
   api_key	Your Hex Trust API key. Secret, from Hex Trust.
   private_key	The ES256 private key used to sign requests to Hex Trust. Pasting it with \n in place of line breaks also works. Secret.
   webhook_public_key	Hex Trust's Ed25519 public key (base64), used to check that webhooks really come from Hex Trust. Without it, every webhook is rejected.
   withdrawal_address	The address withdrawals are sent from.

4. Register the webhook in Hex Trust. Send transaction webhooks to your exchange's API address followed by /plugins/hextrust/webhook. Use this address, with your exchange's API domain in place of <your-api-domain>:

   https://<your-api-domain>/plugins/hextrust/webhook

   Your API domain depends on how your exchange is set up, for example api.yourexchange.com or yourexchange.com/api. See Base URLs to check yours, or open a ticket.

5. Check it's running. Open your exchange's API address followed by /plugins/hextrust/health in a browser. It should show the status ok. Then make a small test deposit and withdrawal.

What your users see

Users deposit and withdraw from their wallet on your exchange as usual. The first time a user asks for a deposit address, the plugin creates a Hex Trust vault for them and derives the address there. If they already have an address on the same network, it is reused.

How it works

Deposits. When Hex Trust reports a deposit, the plugin checks the webhook's signature and refuses it if the signature is missing or wrong. A deposit Hex Trust reports as completed is credited; one it reports as failed is rejected. Deposits for a coin that doesn't exist on your exchange, or has deposits turned off, aren't credited.

Withdrawals. Every minute, the plugin picks up pending withdrawals for coins it can map to a Hex Trust chain and sends them to Hex Trust, one at a time. When Hex Trust reports a withdrawal completed, it is marked complete on your exchange.

What it doesn't do:

• Withdrawals on hold are never sent. If you run a risk-screening plugin or approve withdrawals by hand, a withdrawal goes to Hex Trust only after its hold is cleared.
• Failed withdrawals aren't marked. The plugin only marks withdrawals complete. If a send to Hex Trust fails after Hex Trust received it, or a withdrawal fails at Hex Trust, it stays waiting on your exchange. Check it in Operator Controls → Operations → Withdrawals and in Hex Trust.
• Unmapped coins are skipped. Coins without a matching Hex Trust chain aren't sent for withdrawal and may not get deposit addresses.

Troubleshooting

• The plugin doesn't start. One of the settings is empty. Fill in all six.
• Deposits arrive at Hex Trust but aren't credited. Check the webhook URL and webhook_public_key. Webhooks with a missing or invalid signature are refused.

Need help? Open a ticket from your HollaEx dashboard.