Skip to main content
POST
Create a wallet
Walkthrough: Create a wallet.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Scopes

orders_write
bearer_auth
treasury_write
bearer_auth
orders_write
api_key
treasury_write
api_key

Headers

Idempotency-Key
string | null

Optional client-generated retry key, 1-255 bytes

TetraFi-Version
enum<string>

The dated API version to answer this request in. Without it, an API key's requests use the version the key pinned when it was created, and a member session uses the current version. A value that is not exactly one supported date answers 400 API_VERSION_UNSUPPORTED before anything runs. The response's TetraFi-Version header names the version used.

Available options:
2026-11-17

Path Parameters

workspaceId
string
required

Workspace ID

Body

application/json

An organisation wallet to create (scope organisation): the wallet connection, family, networks and name, the owner group that approves it, and optionally the registered URL the approval page returns each person to.

connectionId
string
required

A workspace wallet connection id, or platform-<provider> for TetraFi's platform account.

displayName
string
required
family
enum<string>
required

A wallet family. Clients must read a family they do not know as one they can't name.

New values may be added; treat unknown values as other.

Available options:
evm,
solana,
tron,
bitcoin
networks
string[]
required

The networks of the family switched on at creation (CAIP-2). Others can be switched on later.

ownerGroup
object
required

The owner group as the person picked it: the people, how many of them must approve, and the confirmations the threshold count depends on.

scope
enum<string>
required

Whose wallet is being created.

New values may be added; treat unknown values as other.

Available options:
personal,
organisation
returnUrl
string | null

Where TetraFi's approval page sends each person of an organisation wallet back once the signing page has recorded their part: an https URL (plain http only on localhost) whose exact origin (scheme, host and port) is one of the workspace's registered embedded-wallet callback origins. The person returns to it with signingRequestId and outcome added to its query: approved (their part is recorded), pending (recorded, the wallet waits for others) or refused (the signing page refused to finish; the person is shown why first and goes back only when they choose). Any other URL, and one on TetraFi's own app or signing origin, is refused with 400 RETURN_URL_NOT_REGISTERED.

visibility
enum<string>

An organisation wallet's visibility to the workspace, as the organisation setup form states it; readable when absent. Refused for a personal wallet.

Available options:
readable,
discoverable,
hidden

Response

A creation body: the pending wallet and the caller's signing request. Nothing exists at the provider until the signing page completes it

202 for a creation body: the pending wallet and the caller's signing request.

signingRequest
object
required

The creation's signing request: its id, and the approval page each person of the wallet opens to set up their factors and approve.

status
enum<string>
required

The state of a wallet being created. Clients must read a value they do not know as not usable yet.

New values may be added; treat unknown values as other.

Available options:
pending,
creating,
uncertain,
created,
active,
readbackMismatch,
failed,
expired,
cancelled,
declined
wallet
object
required

A wallet being created: what was asked for, who is still missing and where it stands.

walletId
string
required

The pending wallet's id.