Unlink a trader (issues a fresh import key)
Detach the trader from an account before trading starts — wrong customer, refund, resale, or a mistaken import.
What happens:
- The trader is detached (
userIdback tonull) - The old import key is voided forever and a fresh key is issued (returned in the response and in the webhook)
- An
account.unlinkedwebhook fires with the unlinked trader’s email, the voided key, and the new key - If the account was created with a
claimEmail, it is cleared, so the same login does not claim the account straight back. Hand over the fresh key instead.
Soulbound bindings are NOT released by unlink. If the account’s customerId is bound to a Hyperprop login, the fresh key can still only be redeemed by that same login. That’s intentional — the binding belongs to the customer, not the account. Two follow-ups depending on why you’re unlinking:
- Resold to a different customer → change the account’s
customerIdto the new customer’s ID (PATCH /trading-accounts/{accountId}), then hand over the fresh key. - Same customer, lost Hyperprop login → rebind the customer to their new login (
POST /trader-bindings/{bindingId}/rebind) — the fresh key then becomes redeemable by the new login, and any still-active accounts on the old login are failed.
When it’s refused — 409 ACCOUNT_ALREADY_STARTED:
Only not_started accounts with zero order history, no open position and no working order can be unlinked. While the unlink runs, an order the trader sends on the account is refused. Once a trader has placed trades there is history, journal data, and snapshots that belong to them — unlinking would orphan all of it. Handle post-start situations with account status changes (PATCH /trading-accounts/{accountId}/status) instead.
Note: if the import had already started a billing cycle, that cycle is not reversed — the new redemption of the fresh key will not double-bill inside the same cycle window.
Permissions: organization admins only.
When it’s refused — 503 ENGINE_UNAVAILABLE: the trading engine did not confirm the account is idle. Nothing changed; retry in a moment.
Error codes: ACCOUNT_NOT_FOUND, NOT_LINKED, ACCOUNT_ALREADY_STARTED, ENGINE_UNAVAILABLE, UNLINK_ERROR.
Access: full-access API keys only (a read-only key gets 403 READ_ONLY_KEY). Dashboard members need manage access to Traders & accounts.
curl --request POST \
--url https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink"
headers = {"X-API-Key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Trader unlinked — a fresh import key was issued (the old key is void)",
"data": {
"id": "<string>",
"userId": "<string>",
"unlinkedUserId": "<string>",
"unlinkedEmail": "<string>",
"importKey": "HP-9WM4T-K2XQ7-3RFPD"
}
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "\"limit\" must be less than or equal to 100",
"code": "VALIDATION_ERROR"
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Only organization admins can perform this action",
"code": "NOT_ADMIN"
}{
"success": false,
"statusCode": 404,
"error": "Not Found",
"message": "Account not found in your organization",
"code": "ACCOUNT_NOT_FOUND"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "Account has already started trading, or has an open position or a working order — unlinking would orphan the trader's history",
"code": "ACCOUNT_ALREADY_STARTED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"success": false,
"statusCode": 503,
"error": "Error",
"message": "The trading engine did not confirm the account is idle; nothing changed, retry in a moment",
"code": "ENGINE_UNAVAILABLE"
}Authorizations
Organization API key (hp_live_...), sent in the X-API-Key header. Create, rotate and restrict keys in the dashboard or with the API keys endpoints; an organization can have two active keys, so you can rotate without downtime. A full-access key can call every endpoint in this reference. A read-only key can call GET endpoints (and create a trading stream token); any other request returns 403 READ_ONLY_KEY. A key with an IP allowlist returns 403 IP_NOT_ALLOWED from any other address. Each endpoint lists which keys can call it under Access.
Headers
Optional. A value that identifies this operation on your side, at most 255 characters. A retry with the same key, method, path and body within 24 hours returns the original response (with Idempotency-Replayed: true) instead of repeating the change. The same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED; a retry while the first request is still running returns 409 IDEMPOTENCY_KEY_IN_PROGRESS. A response that contains a credential (such as a new API key or signing secret) is not saved: the change is still not repeated, and a retry returns 409 IDEMPOTENCY_KEY_COMPLETED with the original status in originalStatus. Server errors (5xx) are not saved, so a retry runs again. If the key cannot be recorded, the request is not run and returns 503 IDEMPOTENCY_UNAVAILABLE; retry with the same key.
255curl --request POST \
--url https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink"
headers = {"X-API-Key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hyperprop.com/platform/v1/organization/trading-accounts/{accountId}/unlink")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Trader unlinked — a fresh import key was issued (the old key is void)",
"data": {
"id": "<string>",
"userId": "<string>",
"unlinkedUserId": "<string>",
"unlinkedEmail": "<string>",
"importKey": "HP-9WM4T-K2XQ7-3RFPD"
}
}{
"success": false,
"statusCode": 400,
"error": "Bad Request",
"message": "\"limit\" must be less than or equal to 100",
"code": "VALIDATION_ERROR"
}{
"success": false,
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication required",
"code": "UNAUTHORIZED"
}{
"success": false,
"statusCode": 403,
"error": "Forbidden",
"message": "Only organization admins can perform this action",
"code": "NOT_ADMIN"
}{
"success": false,
"statusCode": 404,
"error": "Not Found",
"message": "Account not found in your organization",
"code": "ACCOUNT_NOT_FOUND"
}{
"success": false,
"statusCode": 409,
"error": "Conflict",
"message": "Account has already started trading, or has an open position or a working order — unlinking would orphan the trader's history",
"code": "ACCOUNT_ALREADY_STARTED"
}{
"success": false,
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"code": "INTERNAL_ERROR"
}{
"success": false,
"statusCode": 503,
"error": "Error",
"message": "The trading engine did not confirm the account is idle; nothing changed, retry in a moment",
"code": "ENGINE_UNAVAILABLE"
}