createWallet

Create one network-scoped signing identity in an explicit control mode.

GroupWallet lifecycle

RuntimesTypeScript browser/server, React client adapter, Python/Go server

Updated2026-09-16

Status

Proposed target SDK behavior for implementation. This is not an available SDK, an implementation-ready contract, or a change to the approved Streams PRD.

One wallet is one network-scoped key and address with a stable wallet ID and a controlMode fixed at creation. Neither mode returns raw custody material. Public reads expose safe summaries of mode, authority, address, grants, limits and effective policy assignments — never credentials, signing material or authorization proofs.

Business action#

Create one network-scoped wallet signing identity and address in an explicitly selected embedded or server control mode. The SDK exposes the wallet and operation result; custody preparation remains internal.

Proposed call#

createWallet(
  input: CreateWalletInput,
  options?: CallOptions,
): Promise<Operation<CreateWalletResult>>

CreateWalletInput uses requestId, network, required controlMode, mode-appropriate owner or serviceIdentity, initial policies/transaction limits, optional name, and optional authorization. CreateWalletResult contains the completed wallet projection and safe storage disposition.

async def create_wallet(
    input: CreateWalletInput,
    *,
    options: CallOptions | None = None,
) -> Operation[CreateWalletResult]: ...

The Python DTO exposes request_id; name uses UNSET when omitted. None is not a request to clear the name during creation.

CreateWallet(
    ctx context.Context,
    input *CreateWalletInput,
) (*Operation[CreateWalletResult], error)

The Go DTO exposes RequestID, Network, ControlMode, the mode-appropriate authority, limits, and optional Name with stable JSON tags. A nil input, missing mode or invalid required field returns an error before submission.

Required input:

requestId: stable caller identity for this operation;
network: supported network identifier;
controlMode: exactly embedded or server, with no default;
owner: required owner identity for embedded mode;
serviceIdentity: required treasury/payout authority for server mode;
initial policies and transaction limits appropriate to that authority;
optional display name;
authorization supplied by the configured application handler when required.

The target model is one network-scoped key/address. No mnemonic length, derivation path, derived-account, or mnemonic-export capability is promised.

Result and operation recovery#

Success returns wallet ID, immutable control mode, network, address, public signing metadata, controlling owner/service identity, granted rights, limits and safe storage disposition. Embedded custody stays owner-controlled. Server authority stays in the protected remote signer under the named service identity. Custody material is never a public result. Creation in one mode never creates or migrates the other.

The SDK binds requestId to immutable owner, network, payload and required authority context. Authorization responses bind to that record but are accumulated separately, so a valid response does not change operation material. Same-ID/same-material replay converges on the prior operation; same ID with different material conflicts. After an uncertain outcome, call getOperation(requestId) instead of creating another wallet. The retained identity horizon and expired-identity behavior must be specified before implementation; expiry never authorizes blind repetition.

Authorization and effects#

The operation may complete under existing authority. Otherwise the SDK invokes the mode-appropriate owner/service handler once or returns requiresAction; it cannot do both. Proof binds action, mode, wallet target, actor/service identity, request ID and payload. End-user login never substitutes for server-wallet service authorization.

Successful completion creates exactly one wallet identity. Rejection or conflict creates none. It does not fund, monitor, export or transfer the wallet.

Acceptance#

Positive: an authorized request yields one readable wallet with the expected network/address and owner rights; retry and restart recover the same result.
Negative: changed material cannot reuse the request ID; unresolved completion is not success; no unsupported mnemonic/account capability, implicit mode, silent migration or browser secret disclosure is introduced.

See SDK model and business stories, getWallet, and getOperation.