> This page is for Taurus PROTECT, version v3.56. > For other versions, use one of these documentation indexes: > - v3.58 (default): https://taurushq.ferndocs.com/protect-capital/v3.58/llms.txt > - v3.56: https://taurushq.ferndocs.com/protect-capital/v3.56/llms.txt > - v3.54: https://taurushq.ferndocs.com/protect-capital/v3.54/llms.txt > - v3.52: https://taurushq.ferndocs.com/protect-capital/v3.52/llms.txt > - v3.50: https://taurushq.ferndocs.com/protect-capital/v3.50/llms.txt > - v3.48: https://taurushq.ferndocs.com/protect-capital/v3.48/llms.txt > - v3.46: https://taurushq.ferndocs.com/protect-capital/v3.46/llms.txt > - v3.44: https://taurushq.ferndocs.com/protect-capital/v3.44/llms.txt > - v3.42: https://taurushq.ferndocs.com/protect-capital/v3.42/llms.txt > - v3.40: https://taurushq.ferndocs.com/protect-capital/v3.40/llms.txt > - v3.38: https://taurushq.ferndocs.com/protect-capital/v3.38/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://taurushq.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://taurushq.ferndocs.com/_mcp/server. # Create an address POST https://your-protect-instance.example.com/api/rest/v1/addresses Content-Type: application/json This endpoint creates a new address within a specified Wallet. All addresses _must_ be associated with a parent wallet. Addresses created with this endpoint are internal to Protect. To create an external address, you need to create a [whitelisted address request](https://docs.taurushq.com/protect-capital/reference/whitelistservice_createwhitelistedaddress). For more information about whitelisted assets, see our [user guides](https://docs.taurushq.com/user-and-technical-guides/docs/smart-contracts). Address creation requires HSM signature, which makes it synchronous. Therefore, address creation can be slow, and failures may occur if the HSM is either unavailable or takes too long to process. If this happens, the API can be safely called again. **Required role:** AccountCreator. Reference: https://taurushq.ferndocs.com/protect-capital/reference/addresses/create ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a tgvalidatordCreateAddressRequest. - `walletId` (string, required) — Unique identifier for the wallet in which the address will be created. Must be an existing wallet ID. In Protect, a wallet represents a logical collection of addresses. - `label` (string, required) — A human-readable label for the address. Displayed as `Name` in the UI. - `comment` (string, optional) — Optional comment for additional information about the address. - `customerId` (string, optional) — ID of the customer that owns the address. Automatically set if address belongs to an omnibus (shared) wallet. - `nonHardenedDerivation` (boolean, optional) — Indicates whether non-hardened derivation should be used for address creation. Default (recommended value) is false. - `workchainId` (integer, optional) — Workchain identifier. Used for smart contracts on blockchains like TON. - `type` (string, optional) — Address type, specific to the blockchain being used. For BTC & LTC, valid values are ``p2pkh``, ``p2sh_p2wpkh``, or ``p2wpkh``. Defaults to ``p2sh_p2wpkh`` if empty. For DOGE, value must be ``p2pkh``. Will default to ``p2pkh`` if empty. For all other blockchains, this field must be empty. - `externalAddressId` (string, optional) — Identifier for the address in the user's system. This must be unique. Attempting to create an address with an existing externalAddressId will return the originally created address instead of creating a new one. ## Response ### 200 A successful response. - `result` (tgvalidatordAddress, optional) ## Errors ### 400 Bad Request Error Bad Request: indicates that the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing) - `any` ### 401 Unauthorized Error Unauthorized: indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource - `any` ### 403 Forbidden Error Forbidden: indicates that the server understands the request but refuses to authorize it - `any` ### 404 Not Found Error Not Found: indicates that the server cannot find the requested resource - `any` ### 500 Internal Server Error Internal Server Error: indicates that the server encountered an unexpected condition that prevented it from fulfilling the request - `any` ### 503 Service Unavailable Error Service Unavailable: indicates that the server is not ready to handle the request. - `any` ## Types ### tgvalidatordAddress - `id` (string, optional) — uint64; Unique identifier for the address. - `walletId` (string, optional) — uint64; Unique identifier for the wallet associated with the address (parent wallet) - `seed` (string, optional) — Which seed in the HSM to use for address generation.. - `currency` (string, optional) — Currency associated with the address (e.g., ETH, BTC). For a list of enabled currencies, query the [currencies endpoint](https://docs.taurushq.com/protect-capital/reference/walletservice_getcurrencies). - `addressPath` (string, optional) — The derivation path for the address, used to generate the address from the seed. - `addressIndex` (string, optional) — uint64; Index used for address generation. Required for derivation paths. - `address` (string, optional) — The actual address generated for the wallet. - `alternateAddress` (string, optional) — An alternate address that can be used for transactions, if available. - `comment` (string, optional) — An optional comment associated with the address. - `label` (string, optional) — A user-friendly label for the address (e.g., 'Deposit Address'). Displayed as `Name` in the UI. - `customerId` (string, optional) — Identifier for the customer associated with the address. - `nonce` (string, optional) — uint64; The current nonce of the address. A nonce is a 32-bit (or 4-byte) number used to prevent replay attacks. - `balance` (tgvalidatordBalance, optional) - `signature` (string, optional) — Signature associated with the address. - `scores` (list of tgvalidatordScore, optional) — Risk score related to the address, pulled from external reputation services. (e.g., Scorechain, Chainalysis, etc...). - `attributes` (list of tgvalidatordAddressAttribute, optional) — Additional attributes and metadata associated with the address. - `linkedWhitelistedAddressIds` (list of string, optional) — List of whitelisted address IDs that are linked to this address. - `creationDate` (datetime, optional) — The date and time when the address was created. - `updateDate` (datetime, optional) — The date and time when the address was last updated. - `walletInfo` (tgvalidatordWalletInfo, optional) - `disabled` (boolean, optional) — Indicates whether the address is disabled. - `currencyInfo` (tgvalidatordCurrency, optional) - `canUseAllFunds` (boolean, optional) — Indicates whether all funds in the address can be used. - `externalAddressId` (string, optional) — An optional external identifier for the address. - `status` (string, optional) — Status of address creation. Creating status is used for asynchronous address creation. Value is one of `created`, `creating, `signed`, `observed`, or `confirmed`. ### tgvalidatordBalance - `totalConfirmed` (string, optional) — Total confirmed balance in the smallest currency unit (e.g., WEI for ETH). - `totalUnconfirmed` (string, optional) — Total balance including unconfirmed transactions in smallest currency unit (e.g., WEI). Exceeds totalConfirmed when transactions are pending confirmation. Equal to confirmed balance when all funds are confirmed. - `availableConfirmed` (string, optional) — Available confirmed balance that is ready to be spent or used. - `availableUnconfirmed` (string, optional) — Available balance including unconfirmed transactions. - `reservedConfirmed` (string, optional) — Confirmed reserved balance that is set being held for specific purposes, such as another pending transactions. - `reservedUnconfirmed` (string, optional) — Reserved unconfirmed balance that is not yet fully validated. ### tgvalidatordScore - `id` (string, optional) - `provider` (string, optional) - `type` (string, optional) - `score` (string, optional) - `updateDate` (datetime, optional) ### tgvalidatordAddressAttribute - `key` (string, optional) — A key that Protect assigns to the attribute. E.g., `legacyAddress` `has_any_transactions`, etc... - `value` (string, optional) — The value of the attribute. - `id` (string, optional) — Unique identifier for the attribute. - `contentType` (string, optional) — Content type of the attribute value. Usually `text/plain.` - `owner` (string, optional) — Owner of the attribute. Most commonly `system` or `user`. - `type` (string, optional) — A Protect generated attribute type. E.g., `transaction_info`, `tag`, etc... - `subtype` (string, optional) — A Protect generated subtype. Not commonly used but can be used to further classify the attribute. - `isfile` (boolean, optional) — Indicates whether the attribute is a file. ### tgvalidatordWalletInfo - `id` (string, optional) - `balance` (tgvalidatordBalance, optional) - `currency` (string, optional) - `coin` (string, optional) - `name` (string, optional) - `container` (string, optional) - `seed` (string, optional) - `accountPath` (string, optional) - `isOmnibus` (boolean, optional) - `creationDate` (datetime, optional) - `updateDate` (datetime, optional) - `customerId` (string, optional) - `comment` (string, optional) - `disabled` (boolean, optional) - `blockchain` (string, optional) - `addressesCount` (string, optional) - `currencyInfo` (tgvalidatordCurrency, optional) - `attributes` (list of tgvalidatordWalletAttribute, optional) - `network` (string, optional) - `visibilityGroupID` (string, optional) - `externalWalletId` (string, optional) — An optional external identifier for the wallet. ### tgvalidatordCurrency - `name` (string, optional) — Name of the currency. - `symbol` (string, optional) — Shorthand symbol for the currency. - `coinTypeIndex` (string, optional) — Index used to identify the coin type in BIP44. (e.g. Bitcoin is 0, Ethereum is 60). - `blockchain` (string, optional) — The Blockchain the currency is associated with, (e.g. ETH, BTC). - `isToken` (boolean, optional) — Indicates if the currency is a token (e.g., ERC-20). - `isERC20` (boolean, optional) — DEPRECATED: use tokenInfo.tokenType == ERC20 instead. - `decimals` (string, optional) — Number of decimal places the currency uses (e.g. 18 for ETH). - `contractAddress` (string, optional) — Smart contract address if currency is a smart contract (e.g. ERC-20.). - `hasStaking` (boolean, optional) — Indicates if the currency supports staking. - `isUTXOBased` (boolean, optional) — Indicates if the currency is UTXO-based (e.g. Bitcoin). - `isAccountBased` (boolean, optional) — Indicates if the currency is account-based (e.g. Ethereum). - `isFiat` (boolean, optional) — Indicates if the currency is a fiat currency (e.g. CHF, EUR, USD). - `isFA12` (boolean, optional) — DEPRECATED: use tokenInfo.tokenType == FA12 instead. - `isFA20` (boolean, optional) — DEPRECATED: use tokenInfo.tokenType == FA2 instead. - `isNFT` (boolean, optional) — Indicates if the currency represents a Non-Fungible Token (NFT). - `enabled` (boolean, optional) — Indicates if the currency is enabled in the current tenant. - `id` (string, optional) — Unique identifier of the currency. - `displayName` (string, optional) — Display name for the currency, (e.g. Ethereum, Bitcoin). - `type` (string, optional) — Type of the currency. Can be `token`, `fiat`, `native` , or `signet`. - `wlcaId` (string, optional) — White listed contract address id associated with the currency. - `network` (string, optional) — Network or environment the currency is used on (e.g. 'mainnet', 'testnet'). - `tokenID` (string, optional) — Unique id for the token, if applicable (e.g. for NFTs). - `logo` (string, optional) — Currency logo in Data URI scheme. Base 64 encoded. (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==). - `tokenInfo` (tgvalidatordTokenInfo, optional) — Token-specific details for a Currency. Present only when the currency is a token. ### tgvalidatordWalletAttribute - `key` (string, optional) - `value` (string, optional) - `id` (string, optional) - `contentType` (string, optional) - `owner` (string, optional) - `type` (string, optional) - `subtype` (string, optional) - `isfile` (boolean, optional) ### tgvalidatordTokenInfo Token-specific details for a Currency. Present only when the currency is a token. - `tokenType` (enum, optional) — Token standard of a currency; set only when it is a token. Replaces isERC20 (6), isFA12 (15), isFA20 (16). - Allowed values: `TOKEN_TYPE_ERC20`, `TOKEN_TYPE_ERC721`, `TOKEN_TYPE_ERC1155`, `TOKEN_TYPE_CRYPTO_PUNKS`, `TOKEN_TYPE_FA2`, `TOKEN_TYPE_FA12`, `TOKEN_TYPE_ASA`, `TOKEN_TYPE_COSMOS_BANK`, `TOKEN_TYPE_CW20`, `TOKEN_TYPE_XLM_ASSET`, `TOKEN_TYPE_SOL_TOKEN`, `TOKEN_TYPE_SOL_TOKEN_2022`, `TOKEN_TYPE_ICRC1`, `TOKEN_TYPE_HEDERA_TOKEN`, `TOKEN_TYPE_HEDERA_NFT`, `TOKEN_TYPE_CANTON_UTILITY`, `TOKEN_TYPE_TRC20`, `TOKEN_TYPE_CIP56`, `TOKEN_TYPE_XRP_ASSET` ## Examples **Request** ```json { "walletId": "123456", "label": "Satoshi genesis address.", "comment": "The first bitcoin address.", "customerId": "7891011", "currency": "BTC" } ``` **Response** ```json { "result": { "id": "987654321", "walletId": "123456", "seed": "btc", "currency": "BTC", "addressPath": "m/44'/0'/0'/0/0", "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "comment": "The first bitcoin address.", "label": "Satoshi genesis address - BTC", "customerId": "customer_7890", "balance": {}, "signature": "XYZSignature", "creationDate": "2025-03-27T15:30:00.000000Z", "updateDate": "2025-03-27T15:30:00.000000Z", "walletInfo": { "id": "123456", "balance": {}, "currency": "BTC", "coin": "BTC", "name": "Satoshi Wallet", "seed": "btc", "accountPath": "m/44'/0'/0'/0", "creationDate": "2025-03-27T15:30:00.000000Z", "updateDate": "2025-03-27T15:30:00.000000Z", "comment": "Collection of addresses used for long term savings. A wallet in Protect is simply a collection of addresses.", "blockchain": "BTC" } } } ``` **SDK Code** ```python import requests url = "https://your-protect-instance.example.com/api/rest/v1/addresses" payload = { "walletId": "123456", "label": "Satoshi genesis address.", "comment": "The first bitcoin address.", "customerId": "7891011", "currency": "BTC" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://your-protect-instance.example.com/api/rest/v1/addresses'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"walletId":"123456","label":"Satoshi genesis address.","comment":"The first bitcoin address.","customerId":"7891011","currency":"BTC"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://your-protect-instance.example.com/api/rest/v1/addresses" payload := strings.NewReader("{\n \"walletId\": \"123456\",\n \"label\": \"Satoshi genesis address.\",\n \"comment\": \"The first bitcoin address.\",\n \"customerId\": \"7891011\",\n \"currency\": \"BTC\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://your-protect-instance.example.com/api/rest/v1/addresses") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"walletId\": \"123456\",\n \"label\": \"Satoshi genesis address.\",\n \"comment\": \"The first bitcoin address.\",\n \"customerId\": \"7891011\",\n \"currency\": \"BTC\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://your-protect-instance.example.com/api/rest/v1/addresses") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"walletId\": \"123456\",\n \"label\": \"Satoshi genesis address.\",\n \"comment\": \"The first bitcoin address.\",\n \"customerId\": \"7891011\",\n \"currency\": \"BTC\"\n}") .asString(); ``` ```php request('POST', 'https://your-protect-instance.example.com/api/rest/v1/addresses', [ 'body' => '{ "walletId": "123456", "label": "Satoshi genesis address.", "comment": "The first bitcoin address.", "customerId": "7891011", "currency": "BTC" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://your-protect-instance.example.com/api/rest/v1/addresses"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"walletId\": \"123456\",\n \"label\": \"Satoshi genesis address.\",\n \"comment\": \"The first bitcoin address.\",\n \"customerId\": \"7891011\",\n \"currency\": \"BTC\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "walletId": "123456", "label": "Satoshi genesis address.", "comment": "The first bitcoin address.", "customerId": "7891011", "currency": "BTC" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://your-protect-instance.example.com/api/rest/v1/addresses")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```