Skip to content

docs(express): createLocalKeyChainV1 API definition #7572

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lokesh-bitgo merged 1 commit into from
Nov 20, 2025
Merged

docs(express): createLocalKeyChainV1 API definition #7572

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 16 additions & 13 deletions modules/express/src/typedRoutes/api/v1/createLocalKeyChain.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,10 @@ import { BitgoExpressError } from '../../schemas/error';
*/
export const CreateLocalKeyChainRequestBody = {
/**
* Optional seed for key generation. If not provided, a random seed with 512 bits
* of entropy will be generated for maximum security. The seed is used to derive a BIP32
* extended key pair.
* Optional seed for deterministic key generation. If not provided, a cryptographically
* secure random seed with 512 bits of entropy will be automatically generated. When providing
* a custom seed, ensure it has sufficient entropy and is generated using a cryptographically
* secure random number generator.
*/
seed: optional(t.string),
};
Expand All @@ -18,26 +19,28 @@ export const CreateLocalKeyChainRequestBody = {
* Response for creating a local keychain
*/
export const CreateLocalKeyChainResponse = t.type({
/** The extended private key in BIP32 format (xprv...) */
/** The extended private key in BIP32 format (xprv...). Keep this secure and never share it. */
xprv: t.string,
/** The extended public key in BIP32 format (xpub...) */
/** The extended public key in BIP32 format (xpub...). Safe to share. */
xpub: t.string,
/** Ethereum address derived from the extended public key (only available when Ethereum utilities are accessible) */
/** Ethereum address derived from the xpub (optional - only present when Ethereum utilities are available) */
ethAddress: optional(t.string),
});

/**
* Create a local keychain
*
* Locally creates a new keychain using BIP32 HD (Hierarchical Deterministic) key derivation.
* This is a client-side operation that does not involve any server-side operations.
* Generates a new BIP32 HD (Hierarchical Deterministic) keychain locally on the Express server.
* This is a local key generation operation that does not communicate with the BitGo service.
* The operation is synchronous and completes immediately.
*
* Returns an object containing the xprv and xpub keys in BIP32 extended key format.
* The created keychain is not known to the BitGo service. To use it with BitGo,
* you must add it using the 'Add Keychain' API call.
* Returns an object containing the xprv (private key) and xpub (public key) in BIP32 extended
* key format. The generated keychain is not registered with BitGo. To use it with BitGo wallets,
* you must add it using the 'Add Keychain' API call (note: only send the xpub, never the xprv).
*
* For security reasons, it is highly recommended that you encrypt the private key
* immediately and securely destroy the unencrypted original to prevent theft.
* **Security:** The response contains the unencrypted private key (xprv). Ensure all
* communications with BitGo Express use TLS/SSL encryption. Encrypt the private key
* immediately upon receipt and securely destroy the unencrypted copy to prevent theft.
*
* @operationId express.v1.keychain.local
* @tag express
Expand Down