New address and key (hosted)
Hosted key generation: returns a new address and private key once, never stored.
# New address and key (hosted)
`POST https://api.rarebl.com/open/address/new`
Generates a new keypair inside the signer, never stores it, and returns it once. The SDKs can also generate keys locally (`keys.generate`).
**Rate class:** write (6 per minute, burst 3, 300 per day, per IP). **Available since:** Open API v2.
**Try It is disabled for this endpoint.** A documentation page should never collect private keys, so Try It is off here. Use the snippets from your own server or an SDK.
## Request
Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.
Example: `curl -X POST "https://api.rarebl.com/open/address/new" -H "Content-Type: application/json" -H "X-Rarebl-Accept-Risk: hosted-signing" -d '{"chain":"btc","type":"p2wpkh"}'`
## Headers
| Header | Required | Description |
| --- | --- | --- |
| `X-Rarebl-Accept-Risk` | Yes | Required acknowledgement that you are sending private keys to a hosted signer. The only accepted value is `hosted-signing`; without it the API answers `API403` `risk_not_acknowledged`. Example: `hosted-signing`. |
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain. One of: btc, ltc, bch, dash, eth, tron. |
| `type` | string | No | Address type, for example `p2wpkh`, `p2pkh`, `p2tr`. One of: p2wpkh, p2pkh, p2sh-p2wpkh, p2tr. |
| `encryptTo` | string | No | Your X25519 public key (base64url). When set, the private key comes back as `encryptedPrivateKey`, an envelope v2 of the same scheme in the other direction (`kid: "client"`); open it with `envelope.decrypt`. |
## Responses
### API200 (HTTP 200): OK
A new keypair. With `encryptTo` the key is returned as `encryptedPrivateKey`.
```json
{
"status": 1,
"code": "API200",
"message": "success",
"data": {
"address": "bc1q9n6w0t7m5x3k2a8d4h1j6f0s5g7c3v2b8l4e9z",
"publicKey": "02f1a6c3d9e7b04a52c8e1d36f7094ba5c21e8d03f6a97b4c15e2d80a3f6b79c41",
"encryptedPrivateKey": "BASE64URL_ENVELOPE_ENCRYPTED_TO_YOUR_X25519_KEY",
"wif": null
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
| Field | Type | Description |
| --- | --- | --- |
| `data.address / publicKey` | string | The new address and its public key. |
| `data.privateKey \| encryptedPrivateKey` | string | The private key (plain) or, with `encryptTo`, encrypted to your key. Shown once; never stored. |
| `data.wif` | string \| null | The WIF for UTXO chains. |
### API403 (HTTP 403): Forbidden
The header `X-Rarebl-Accept-Risk: hosted-signing` is missing.
```json
{
"status": 0,
"code": "API403",
"message": "Hosted signing needs the risk acknowledgement header.",
"data": {
"reason": "risk_not_acknowledged"
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API400 (HTTP 400): Bad Request
A parameter is missing or malformed. `data.param` names it (here `chain`).
```json
{
"status": 0,
"code": "API400",
"message": "Unknown or missing chain.",
"data": {
"param": "chain"
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API429 (HTTP 429): Too Many Requests
Rate limited (write class: 6 per minute, burst 3, 300 per day, per IP). A `Retry-After` header says how long to wait, in seconds.
```json
{
"status": 0,
"code": "API429",
"message": "Too many requests. Please retry shortly.",
"data": null,
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API502 (HTTP 502): Bad Gateway
The node is unavailable, still syncing or timed out. Retry later with a short back-off.
```json
{
"status": 0,
"code": "API502",
"message": "The node is unavailable or timed out. Please try again.",
"data": null,
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
## Notes
- Use `encryptTo` to receive the private key encrypted to your own X25519 key. The plaintext of `encryptedPrivateKey` is `{"privateKeys": ["<64-hex>"]}` and the WIF is omitted in this mode. To generate keys on your machine instead, use the [SDK](https://docs.rarebl.com/guides/sign-locally) (`keys.generate`).
- The keypair is generated in the signer process and never stored. The example shows `encryptedPrivateKey` as a placeholder; no real key appears in these docs.