WalletsTech API Documentation

A user’s wallet set is fixed at /create time, so a user created before a chain was configured has no address on it. /extend derives and inserts wallets for the missing chains only.

The server proves ownership before adding anything: the mnemonic must derive one of the user’s stored addresses (otherwise 403), and the password must decrypt an existing keystore entry (otherwise 401).

Idempotent — when nothing is missing you get added: []. The mnemonic is never returned or stored.

A user's wallet set is fixed at `/create` time, so a user created before a chain was configured has no address on it. `/extend` derives and inserts wallets for the **missing chains only**. The server proves ownership before adding anything: the mnemonic must derive one of the user's stored addresses (otherwise `403`), and the password must decrypt an existing keystore entry (otherwise `401`). Idempotent — when nothing is missing you get `added: []`. The mnemonic is never returned or stored.

Authentication

AuthorizationBearer

A 15-minute token from /auth. Required on every endpoint except /auth.

Request

This endpoint expects an object.

userIdstringRequiredformat: "^[0-9a-fA-F]{24}$"

24-character hex id, returned by /create.

existingSeedstringRequired

bip39 seed phrase, validated with bip39.validateMnemonic.

passwordstringRequired>=8 characters

Keystore password (AES-256-GCM, scrypt KDF). Unrecoverable — required by /send and /extend.

Response

resultobject

requestIdstring

Echo of the inbound X-Request-Id, or a generated one.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

$	curl -X POST https://your-endpoint.example.com/extend \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"userId": "66b1f0c23d4e4a5b9c6d7e8f",
>	"existingSeed": "<your 12-word seed phrase — returned once, never again>",
>	"password": "changeme123"
>	}'

1	{
2	"result": {
3	"userId": "66b1f0c23d4e4a5b9c6d7e8f",
4	"added": [
5	"SOLANA"
6	],
7	"addresses": {
8	"BITCOIN": "bc1q5psk2q8t4x495ap75zghxmyvlmk59lr2u93r6j",
9	"BNB": "0xc0c548339ee2af89c078200cabd1b7c7b47d911a",
10	"ETHEREUM": "0xc0c548339ee2af89c078200cabd1b7c7b47d911a",
11	"POLYGON": "0xc0c548339ee2af89c078200cabd1b7c7b47d911a",
12	"SOLANA": "EB81pobCpSX16xKeuwYyNMDuZEcpWuHcmimQ9LbdT63d",
13	"TRON": "THxvJmtZghePy5XqDE7HKawvFAsAgxcWZt"
14	}
15	},
16	"requestId": "b7a1f0c2-3d4e-4a5b-9c6d-7e8f90a1b2c3"
17	}

Add missing chains

Authentication

Headers

Request

Response

Errors