Submit a Wallet

POST https://trade-uk.sandbox.zodiamarkets.com/api/3/ssi/wallets

Ask Zodia Markets to add a crypto wallet under your own onboarded entity, or under an existing beneficiary or sender.

A submitted wallet is a request

Zodia Markets Operations must review and approve it before it can be used for settlement or withdrawals. Until then it is pending and unusable.

Permissions

The API key needs the Move Funds permission, and your user needs ROLE_OPERATIONS on the accountGroupUuid you name.

Not idempotent

A retry with a fresh nonce can raise a second request. On a timeout, a 500 or a 502, call List Wallet Requests before resending.

---

Choosing the participant

participantUuid names who the wallet belongs to:

To add a wallet for	Take uuid from
Your own onboarded entity	Get Account Details List
An existing beneficiary	Get Beneficiary List
An existing sender	Get Sender List

The participant must be one of yours, for the account group you name. Otherwise the call returns 400 Originator record not found — please contact support, whichever kind of participant you named. You cannot create a new beneficiary or sender here; contact your relationship manager for that.

---

Before you call

accountGroupUuid, participantUuid, blockchain, asset, address and alias are required. memo is optional and limited to 1024 characters. A missing or empty required field returns 403 Invalid signed params without naming the field, so validate client-side against the table below.

The address is checked against the format of the blockchain you name, and a malformed one is refused with 400 and a message describing the problem.

walletType, vasp, executionProvider, direction and defaultWallet are optional, and Operations reviews what you declare. A request for defaultWallet: true is refused if the participant already has a default wallet for that asset and blockchain.

enabled, whitelisted and verified cannot be set

The body has no field for any of them. They are set by Zodia Markets, and a property of that name in the body is ignored.

---

After it succeeds

The call returns approvalRequestId and status: PENDING. The request appears on List Wallet Requests, with kind set to the participant’s kind, as PENDING_SCREENING.

Once Operations approves it, the request drops off that list and the wallet appears under its participant on the matching Get endpoint. Use it only when that endpoint reports enabled: true and whitelisted: true. If Operations declines it, the request is listed as REJECTED; contact your relationship manager for the reason. See Adding a bank account or wallet.

Domain: Payment participants

Note

This call is not idempotent and there is no idempotency key. Resending with a fresh nonce or tonce can raise a second review request. If a submit times out or returns 500 or 502, call List Wallet Requests first, and resubmit only if the request is not there.

Request

POST https://trade-uk.sandbox.zodiamarkets.com/api/3/ssi/wallets

Headers

Header	Required	Description
Rest-Key	yes	API key for authentication
Rest-Sign	yes	Calculated API Signature

Body

Field	Type	Required	Description
tonce	integer (int64)	yes	The current Unix time in microseconds. Accepted only within two minutes of server time. Send either tonce or nonce.
nonce	integer (int64)		Alternative to tonce, and takes precedence when both are sent. Must be a whole number and strictly increasing for a given API key: a reused or lower value is rejected. A request carrying neither nonce nor tonce is rejected with 401.
accountGroupUuid	string	yes	The account group you are acting for. You must hold ROLE_OPERATIONS on it.
participantUuid	string	yes	The participant the new entry is added under: your own onboarded entity (the uuid from Get Account Details List), or an existing beneficiary or sender (the uuid from Get Beneficiary List or Get Sender List). It must be one of yours. A new beneficiary or sender cannot be created through this API.
blockchain	string	yes	The blockchain the wallet is on. It must be one Zodia Markets supports for your account.
asset	string	yes	The asset the wallet will hold, for example USDC.
address	string	yes	The wallet address. It is checked against the format of blockchain.
alias	string	yes	Your own name for the wallet.
memo	string		Optional free text, up to 1024 characters.
walletType	string (enum)		Optional. Whether the wallet is self-hosted or held with a custodian. When omitted, Zodia Markets applies its default. — One of: SELF_HOSTED, CUSTODY
vasp	string		Optional. For a custodial wallet, the custodian (VASP) that holds it. Free text, reviewed by Operations.
executionProvider	string		Optional. For a custodial wallet, the execution provider.
direction	string		Optional. Which way the wallet is used. When omitted, Zodia Markets applies its default.
defaultWallet	boolean		Optional. Ask for this wallet to become the default for its asset and blockchain on the participant. Refused if another wallet already is.

Responses

200 OK

Request accepted for review by Zodia Markets Operations. The bank account or wallet is not usable yet.

Body

Field	Type	Required	Description
success	boolean
approvalRequestId	integer (int64)		Identifier of the review request. Quote it to your relationship manager, and match it against the id returned by the wallet requests list.
status	string		PENDING: awaiting review by Zodia Markets Operations. The list endpoint reports the same state as PENDING_SCREENING.

400 Bad Request

The request was not created.

message	Cause
Originator record not found — please contact support	participantUuid does not identify one of your participants for this account group. The message reads Originator whichever kind of participant you named
<field>: <reason>, several joined by ;	The details failed validation, for example an address that is not valid for the blockchain
Another reason, or The submitted details were rejected	The details were refused for a reason not covered above

Body

Field	Type	Required	Description
success	boolean
message	string

401 Unauthorized

Authentication failed: unknown key, bad signature, a missing, malformed, reused or decreasing nonce or out-of-window tonce, a body that is not parseable JSON, or a throttled caller. Rate limiting surfaces here as 401, not 429.

Body

Field	Type	Required	Description
success	boolean
message	string

403 Forbidden

Body missing or failed field validation (Invalid signed params), the API key lacks the Move Funds permission (MOVE FUNDS permission required), or you do not hold ROLE_OPERATIONS on accountGroupUuid (You do not have permission to perform this action). The message does not name the field or the permission at fault. Required: accountGroupUuid, participantUuid, blockchain, asset, address, alias; memo at most 1024 characters.

Body

Field	Type	Required	Description
success	boolean
message	string

500 Internal Server Error

Unexpected error. The outcome is undefined.

Body

Field	Type	Required	Description
success	boolean
message	string

502

The service that holds bank accounts and wallets could not be reached or returned an unusable answer. The outcome is undefined: call the matching list endpoint before resending.

Body

Field	Type	Required	Description
success	boolean
message	string