> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletsuite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> A method-by-method guide to the wallet SDK: clients, arguments, return shapes, and dual-language examples for creating wallets, deriving addresses, and signing transactions.

This is the per-method guide to the wallet SDK. For a guided first run, start with the [Quickstart](/mpc/quickstart). For the conceptual model, see [MPC Wallets Overview](/mpc/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](/getting-started/prerequisites/credentials-and-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.

<CodeGroup>
  ```js client.js theme={null}
  const { MpcClient } = require("@walletsuite/wallet");

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

  ```python client_sync.py theme={null}
  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
  )
  ```

  ```python client_async.py theme={null}
  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
  )
  ```
</CodeGroup>

### 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            |

<Note>
  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.
</Note>

## 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.

<CodeGroup>
  ```js create.js theme={null}
  // Covers every chain
  const wallet = await client.createWallet();

  await saveWallet(wallet); // your storage
  ```

  ```python create.py theme={null}
  # Covers every chain
  wallet = client.create_wallet()

  save_wallet(wallet)  # your storage
  ```
</CodeGroup>

<Note>
  Wallets are 2-of-2 by default, so keep the wallet you hold in durable storage before you continue. See [Shares & thresholds](/mpc/key-shares).
</Note>

## 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](/supported-chains).

<CodeGroup>
  ```js derive.js theme={null}
  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");
  ```

  ```python derive.py theme={null}
  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")
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```js sign_1559.js theme={null}
  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
  );
  ```

  ```python sign_1559.py theme={null}
  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
  )
  ```
</CodeGroup>

## 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](/mpc/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.

<Note>
  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`.
</Note>

<CodeGroup>
  ```js sign_7702.js theme={null}
  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
  ```

  ```python sign_7702.py theme={null}
  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
  ```
</CodeGroup>

## 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. |

<CodeGroup>
  ```js sign_tron.js theme={null}
  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
  ```

  ```python sign_tron.py theme={null}
  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
  ```
</CodeGroup>

## 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.                                                            |

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

<CodeGroup>
  ```js sign_bitcoin.js theme={null}
  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
  ```

  ```python sign_bitcoin.py theme={null}
  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
  ```
</CodeGroup>

## 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. |

<CodeGroup>
  ```js sign_solana.js theme={null}
  const signed = await client.signSolana(
    wallet,
    "AQABA..."          // messageB64, compiled message
  );

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

  ```python sign_solana.py theme={null}
  signed = client.sign_solana(
      wallet,
      "AQABA...",         # message_b64, compiled message
  )

  signed.signature_hex  # 64-byte signature
  signed.signed_tx_b64  # broadcast-ready transaction
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Signing" icon="signature" href="/mpc/signing">
    The signing methods and the async surface in depth.
  </Card>

  <Card title="Broadcasting" icon="paper-plane" href="/mpc/broadcasting">
    Send the signed transaction through your own RPC or the WalletSuite send endpoint, then check status.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/mpc/errors">
    The Node and Python error model, with a category, cause, and fix table.
  </Card>

  <Card title="Shares & thresholds" icon="key" href="/mpc/key-shares">
    Store the wallet, run the 2-of-2 default, and see what's on the roadmap.
  </Card>
</CardGroup>