Skip to navigation
API ReferenceWallets

Create a user

View as MarkdownOpen in Claude

Creates the user and derives one wallet per configured chain from a single bip39 mnemonic, atomically.

⚠️ The mnemonic is returned exactly once and is never stored in plaintext. Persist it before you discard the response — there is no way to retrieve it afterwards, and no export endpoint.

The password (minimum 8 characters) encrypts the keystore entries with AES-256-GCM. It is unrecoverable and is required by /send and /extend.

Only chains available on your endpoint are created, so a partial address map is normal in development. Chains that become available later are backfilled with /extend.

Authentication

AuthorizationBearer

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

Headers

X-Request-IdstringOptional

Correlation id. Generated if omitted, echoed on every response, and written to the audit log. /send is the exception — there it is required, and it doubles as the idempotency key.

X-USER-IDstringOptionalformat: "^[0-9a-fA-F]{24}$"

Optional. When present it overrides any userId in the body.

Request

This endpoint expects an object.
passwordstringRequired>=8 characters

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

existingSeedstringOptional

bip39 seed phrase, validated with bip39.validateMnemonic.

Response

OK
resultobject
requestIdstring

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

Errors

400
Bad Request Error
401
Unauthorized Error
409
Conflict Error
503
Service Unavailable Error