SDK Reference

This is the per-method guide to the wallet SDK. For a guided first run, start with the Quickstart. For the conceptual model, see MPC Wallets Overview.

Language	Package	Import
Node	`@walletsuite/wallet`	`const { MpcClient } = require("@walletsuite/wallet")`
Python	`walletsuite-wallet`	`import walletsuite_wallet as ws`

Type conventions

The parameter tables below use two shorthand types:

Type	Meaning
`blob`	An opaque wallet returned by `createWallet`. Store it and pass it back. Never inspect or modify it.
`amount`	A non-negative integer quantity. Pass it as a decimal string in Node to stay inside the JavaScript safe-integer range, and as a native `int` in Python.

Clients

You construct a client with the signing service URL and your WalletSuite API key. Use https://cosigner.walletsuite.io in production. The API key is sent on every request. See Credentials & Authentication.

Constructor	Argument	Type	Required	Notes
`MpcClient`	`cosignerUrl`	string	Yes	The WalletSuite signing service endpoint. Use `https://cosigner.walletsuite.io` in production.
	`apiKey`	string	No	Your WalletSuite API key.
	`registerTimeoutSecs`	number	No	Registration timeout in seconds. Defaults to `30`.

Python exposes the same constructor on both MpcClient and AsyncMpcClient, with snake_case keyword arguments.

const { MpcClient } = require("@walletsuite/wallet");

const client = new MpcClient(
  "https://cosigner.walletsuite.io",
  process.env.WALLETSUITE_API_KEY,
  30 // registerTimeoutSecs (optional, default 30)
);

import os
import walletsuite_wallet as ws

client = ws.MpcClient(
    "https://cosigner.walletsuite.io",
    api_key=os.environ["WALLETSUITE_API_KEY"],
    register_timeout_secs=30,  # optional, default 30
)

import os
import walletsuite_wallet as ws

client = ws.AsyncMpcClient(
    "https://cosigner.walletsuite.io",
    api_key=os.environ["WALLETSUITE_API_KEY"],
    register_timeout_secs=30,  # optional, default 30
)

Sync vs async behavior

The signing methods are async in Node and in the Python AsyncMpcClient. The Python MpcClient is fully synchronous. Address derivation is synchronous in every client because it runs locally with no network call.

Client	Signing methods	`deriveAddress`
Node `MpcClient`	async (return Promises)	sync
Python `MpcClient`	sync (blocking)	sync
Python `AsyncMpcClient`	awaitable (coroutines)	sync

The signing methods are createWallet, signEvm1559, signEvm7702, signTron, signBitcoin, and signSolana. They reach the WalletSuite signing service over the network, so it must be reachable. deriveAddress runs locally and never hits the network.

createWallet

Runs the 2-of-2 DKG and returns the wallet you keep. Pass an empty list or omit the argument to cover every chain. You hold the wallet and WalletSuite holds a co-signing share. Neither side ever sees the full key.

Parameter	Type	Required	Notes
`curves`	string[]	No	Curve subset. Omit or pass `[]` to cover every chain. Valid entries: `secp256k1` (EVM, Bitcoin, Tron), `ed25519` (Solana).

Returns the wallet: one opaque string you store and pass back on every call. It is exactly what deriveAddress and the sign* methods take. Recover its key id any time with walletKeyId(wallet) (Node) or wallet_key_id(wallet) (Python), a local call with no network.

// Covers every chain
const wallet = await client.createWallet();

await saveWallet(wallet); // your storage

# Covers every chain
wallet = client.create_wallet()

save_wallet(wallet)  # your storage

Wallets are 2-of-2 by default, so keep the wallet you hold in durable storage before you continue. See Shares & thresholds.

deriveAddress

Derives the on-chain address from the wallet. This is local and synchronous in every client.

Parameter	Type	Required	Notes
`wallet`	blob	Yes	The wallet returned by `createWallet`.
`chain`	string	Yes	Lowercase chain identifier (see below).
`path`	string	No	Custom derivation path. Supported on EVM chains, Bitcoin, and Tron.

Returns the address string for the chain. One wallet works everywhere. The same wallet derives addresses across 84 chains including Ethereum, Base, Bitcoin, Solana, Tron, and more. Pass the chain identifier as a lowercase string. Every EVM chain (ethereum, base, polygon, binance_smart_chain, and the rest) produces the same EIP-55 address, so you can pass whichever chain you are actually deriving for. The deriveAddress identifiers are not always the same as the API’s chain parameter. The table below lists the ones that differ:

Chain	`deriveAddress` identifier	API `chain` parameter
EVM chains	the target chain, e.g. `ethereum`, `base`, `polygon`	`ethereum`, `base`, `polygon`, etc.
BNB Smart Chain	`binance_smart_chain`	`smartchain`
Bitcoin	`bitcoin`	`bitcoin`
Solana	`solana`	`solana`
Tron	`tron`	`tron`

See Supported chains.

const eth = client.deriveAddress(wallet, "ethereum");
const btc = client.deriveAddress(wallet, "bitcoin");
const sol = client.deriveAddress(wallet, "solana");

// EVM chains support a custom path
const eth1 = client.deriveAddress(wallet, "ethereum", "m/44'/60'/0'/0/1");

eth = client.derive_address(wallet, "ethereum")
btc = client.derive_address(wallet, "bitcoin")
sol = client.derive_address(wallet, "solana")

# EVM chains support a custom path
eth1 = client.derive_address(wallet, "ethereum", "m/44'/60'/0'/0/1")

signEvm1559

Signs a plain EVM transaction and returns a raw signed transaction string, ready to broadcast. Use signEvm7702 for EIP-7702 batched transactions.

Parameter	Type	Required	Notes
`wallet`	blob	Yes	The wallet returned by `createWallet`.
`chainId`	number	Yes	EVM chain id.
`nonce`	number	Yes	Account nonce.
`to`	string	Yes	Recipient address.
`value`	amount	Yes	Amount in wei. Decimal string in Node, int in Python.
`maxPriorityFeePerGas`	amount	Yes	Per-gas fee in wei. Decimal string in Node, int in Python.
`maxFeePerGas`	amount	Yes	Per-gas fee in wei. Decimal string in Node, int in Python.
`gasLimit`	number	Yes	Gas limit.
`data`	string	No	Calldata hex. Omit for a plain transfer.
`path`	string	No	Custom derivation path.

Returns the raw signed transaction string, ready to broadcast.

const rawTx = await client.signEvm1559(
  wallet,
  8453,             // chainId (Base)
  0,                // nonce
  "0xRecipientAddress",
  "1000000000000",  // value, wei
  "1000000000",     // maxPriorityFeePerGas, wei
  "2000000000",     // maxFeePerGas, wei
  21000,            // gasLimit
  null,             // data
  null              // path
);

raw_tx = client.sign_evm_1559(
    wallet,
    8453,               # chain_id (Base)
    0,                  # nonce
    "0xRecipientAddress",
    1_000_000_000_000,  # value, wei
    1_000_000_000,      # max_priority_fee_per_gas, wei
    2_000_000_000,      # max_fee_per_gas, wei
    21_000,             # gas_limit
)

signEvm7702

The EVM signing method for EIP-7702 batched transactions. It signs the EIP-7702 (type-4) smart-account transaction format. Each signature is authorized automatically: the SDK mints a single-use, payload-bound signing intent for you, so you pass only the transfer. See Signing intents.

Parameter	Type	Required	Notes
`wallet`	blob	Yes	The wallet returned by `createWallet`.
`chainId`	number	Yes	EVM chain id.
`txNonce`	number	Yes	Account nonce.
`to`	string	Yes	Recipient address.
`value`	amount	Yes	Amount in wei, or token base units when `token` is set. String in Node, int in Python.
`maxPriorityFeePerGas`	amount	Yes	Per-gas fee in wei. String in Node, int in Python.
`maxFeePerGas`	amount	Yes	Per-gas fee in wei. String in Node, int in Python.
`gasLimit`	number	Yes	Gas limit.
`token`	string	No	ERC-20 contract address. `null` (Node) or `None` (Python) for native. When set, `value` is in token base units.
`data`	string	No	Calldata hex.
`delegate`	string	No	EIP-7702 delegate contract address. Defaults to the audited Simple7702Account.
`path`	string	No	Custom derivation path.

Returns the signed transaction. The raw field is broadcast-ready.

Amounts are exact integers, so keep them as integers. Node returns each amount as a decimal string (wei, or token base units when token is set). Python returns native int.

const signed = await client.signEvm7702(
  wallet,
  8453,                            // chainId (Base)
  0,                               // txNonce
  "0xRecipientAddress",
  "100000000000000",               // value, wei
  "1000000000",                    // maxPriorityFeePerGas, wei
  "2000000000",                    // maxFeePerGas, wei
  300000,                          // gasLimit
  null,                            // token: ERC-20 address (null for native)
  null,                            // data
  null,                            // delegate
  null                             // path
);

signed.raw; // broadcast-ready transaction

signed = client.sign_evm_7702(
    wallet,
    8453,                              # chain_id (Base)
    0,                                 # tx_nonce
    "0xRecipientAddress",
    100_000_000_000_000,               # value, wei
    1_000_000_000,                     # max_priority_fee_per_gas, wei
    2_000_000_000,                     # max_fee_per_gas, wei
    300_000,                           # gas_limit
)

signed.raw  # broadcast-ready transaction

signTron

Signs a Tron transaction.

Parameter	Type	Required	Notes
`wallet`	blob	Yes	The wallet returned by `createWallet`.
`to`	string	Yes	Recipient Tron address.
`amountSun`	amount	Yes	Amount in sun. Decimal string in Node, int in Python.
`refBlockBytesHex`	string	Yes	Reference block bytes, hex.
`refBlockHashHex`	string	Yes	Reference block hash, hex.
`expirationMs`	amount	Yes	Expiration timestamp, milliseconds. Decimal string in Node, int in Python.
`timestampMs`	amount	Yes	Transaction timestamp, milliseconds. Decimal string in Node, int in Python.
`feeLimit`	amount	No	Fee limit in sun. Decimal string in Node, int in Python.
`path`	string	No	Custom derivation path.

The reference block fields and timestamps come from a recent Tron block, which you read from a Tron RPC or TronGrid getNowBlock call. Returns an object with the signed transaction parts and the assembled transaction.

Field	Meaning
`rawDataHex`	The raw transaction data, hex.
`signatureHex`	The signature, hex.
`txidHex`	The transaction id, hex.
`signedTxHex`	The assembled, broadcast-ready transaction, hex. Post it as `signedTx` to the send endpoint.

const signed = await client.signTron(
  wallet,
  "TRecipientAddress",
  "1000000",          // amountSun
  "abcd",             // refBlockBytesHex
  "0011223344556677", // refBlockHashHex
  String(Date.now() + 60_000), // expirationMs
  String(Date.now()),          // timestampMs
  "10000000",         // feeLimit (optional)
  null                // path
);

signed.txidHex;      // transaction id
signed.signedTxHex;  // broadcast-ready transaction

import time

now_ms = int(time.time() * 1000)

signed = client.sign_tron(
    wallet,
    "TRecipientAddress",
    1_000_000,          # amount_sun
    "abcd",             # ref_block_bytes_hex
    "0011223344556677", # ref_block_hash_hex
    now_ms + 60_000,    # expiration_ms
    now_ms,             # timestamp_ms
    10_000_000,         # fee_limit (optional)
)

signed.txid_hex        # transaction id
signed.signed_tx_hex   # broadcast-ready transaction

signBitcoin

Signs a Bitcoin transaction. You get one signature per input, in input order, plus the payload hash, and assemble the final witness transaction from them.

Parameter	Type	Required	Notes
`wallet`	blob	Yes	The wallet returned by `createWallet`.
`unsignedTxHex`	string	Yes	The unsigned transaction, hex. Build it from your own UTXO source.
`prevouts`	array	Yes	One entry per input, in input order. Each entry is `{ valueSats, scriptPubkeyHex }` in Node and `{ value_sats, script_pubkey_hex }` in Python.
`prevouts[].valueSats`	amount	Yes	The prevout value in satoshis. Decimal string in Node, int in Python (key `value_sats`).
`prevouts[].scriptPubkeyHex`	string	Yes	The prevout scriptPubKey, hex. Key `script_pubkey_hex` in Python.
`path`	string	No	Custom derivation path.

Returns an object with one signature per input.

Field	Meaning
`signaturesHex`	One signature per input, in input order. Assemble the final transaction from these.
`payloadHashHex`	The signed payload hash.

You get one signature per input back. Reassemble them into the final witness transaction (for example with bitcoinjs-lib) before broadcasting.

const signed = await client.signBitcoin(
  wallet,
  "0200000001...",   // unsignedTxHex
  [
    { valueSats: "100000", scriptPubkeyHex: "0014..." }, // input 0
    { valueSats: "50000",  scriptPubkeyHex: "0014..." }  // input 1
  ],
  null               // path
);

signed.signaturesHex;  // one signature per input, in input order
signed.payloadHashHex; // signed payload hash

signed = client.sign_bitcoin(
    wallet,
    "0200000001...",   # unsigned_tx_hex
    [
        {"value_sats": 100_000, "script_pubkey_hex": "0014..."},  # input 0
        {"value_sats": 50_000,  "script_pubkey_hex": "0014..."},  # input 1
    ],
)

signed.signatures_hex    # one signature per input, in input order
signed.payload_hash_hex  # signed payload hash

signSolana

Signs a Solana transaction.

Parameter	Type	Required	Notes
`wallet`	blob	Yes	The wallet returned by `createWallet`.
`messageB64`	string	Yes	The compiled transaction message, base64. Produce it with @solana/web3.js.

Returns an object with the signature and the signed transaction.

Field	Meaning
`signatureHex`	The 64-byte signature, hex.
`signedTxB64`	The signed transaction, base64, ready to broadcast.

const signed = await client.signSolana(
  wallet,
  "AQABA..."          // messageB64, compiled message
);

signed.signatureHex; // 64-byte signature
signed.signedTxB64;  // broadcast-ready transaction

signed = client.sign_solana(
    wallet,
    "AQABA...",         # message_b64, compiled message
)

signed.signature_hex  # 64-byte signature
signed.signed_tx_b64  # broadcast-ready transaction

Next steps

Signing

The signing methods and the async surface in depth.

Broadcasting

Send the signed transaction through your own RPC or the WalletSuite send endpoint, then check status.

Error handling

The Node and Python error model, with a category, cause, and fix table.

Shares & thresholds

Store the wallet, run the 2-of-2 default, and see what’s on the roadmap.

Get Started

Concepts

Building

Reference

Type conventions

Clients

Sync vs async behavior

createWallet

deriveAddress

signEvm1559

signEvm7702

signTron

signBitcoin

signSolana

Next steps

Signing

Broadcasting

Error handling

Shares & thresholds

​Type conventions

​Clients

​Sync vs async behavior

​createWallet

​deriveAddress

​signEvm1559

​signEvm7702

​signTron

​signBitcoin

​signSolana

​Next steps

Signing

Broadcasting

Error handling

Shares & thresholds

Type conventions

Clients

Sync vs async behavior

createWallet

deriveAddress

signEvm1559

signEvm7702

signTron

signBitcoin

signSolana

Next steps