Create a wallet

Introduction

A Swig wallet holds assets and gives each authority a defined set of permissions. Use this flow when onboarding a user or creating an application-controlled wallet. You can supply an initial authority directly, reuse a saved policy template, or reserve an address from a root authority before creating the wallet. The SDK prepares transactions. Your application signs and submits them; the wallet exists on-chain after confirmation. Start with Client setup. Address reservation requires TypeScript 0.12.0 or Python 0.11.0. The Rust reservation examples use the SDK source, pending the next crates.io release.

SDK examples

Create with an initial authority

Create an inline Ed25519 wallet. Use the configured swig client in TypeScript/Python and wallet: WalletClient in Rust.

const created = await swig.wallets.create({
  feePayer,
  initialUser: {
    ed25519: {
      publicKey: userPublicKey,
    },
  },
});

created = await swig.wallets.create(
    fee_payer=fee_payer,
    initial_user={
        "ed25519": {
            "publicKey": user_public_key,
        },
    },
)

use swig_developer_sdk::{PrepareCreateWalletArgs, WalletAuthority};

let created = wallet
    .prepare_create_wallet(PrepareCreateWalletArgs {
        fee_payer,
        policy_id: None,
        initial_user: Some(WalletAuthority::Ed25519 {
            public_key: user_public_key,
        }),
    })
    .await?;

For a saved template, supply policyId / policy_id; in Rust, use policy_id: Some(policy_id) and set initial_user only when the template needs it. TypeScript/Python return wallet addresses and an ordered transactions list. Sign and submit every transaction in that order. Rust returns WalletCreation with one transaction. Complete embedded signature requests and inspect each transaction’s required Solana signers, including its fee payer. An empty signature-request list can still require an Ed25519 signature. Continue with Signing and Paymaster for sponsored submission.

Create from a policy template

Use the saved template ID. Supply the initial authority only when the template expects an application-provided key.

const created = await swig.wallets.create({
  feePayer,
  policyId,
  initialUser: { ed25519: { publicKey: userPublicKey } },
});

created = await swig.wallets.create(
    fee_payer=fee_payer,
    policy_id=policy_id,
    initial_user={"ed25519": {"publicKey": user_public_key}},
)

use swig_developer_sdk::{PrepareCreateWalletArgs, WalletAuthority};

let created = wallet.prepare_create_wallet(PrepareCreateWalletArgs {
    fee_payer,
    policy_id: Some(policy_id),
    initial_user: Some(WalletAuthority::Ed25519 {
        public_key: user_public_key,
    }),
}).await?;

For composed templates, TypeScript also accepts roleAuthorities, an array of { roleTemplateId, authority } bindings for every additional TBD key. The server rejects missing or duplicate bindings and overrides of stored keys. Python and Rust retain the initial-role flow; use TypeScript for the complete composed template workflow. created.templateSetup contains the current template snapshot and resolved public keys. After creation confirms, apply its additional roles and rent claimer through their SDK operations. Confirm each transaction before preparing the next and inspect the resulting wallet. Recovery settings remain pending: hosted recovery setup is not currently supported; see Guardian recovery for the separate protocol integration. Do not report the full template as applied merely because wallet creation confirmed.

Reserve an address

Derive the wallet’s addresses from a root authority and an optional account index or salt. Address lookup creates no wallet or reservation record; the request counts toward API usage. Keep the same authority and options for activation.

const reserved = await swig.wallets.reserveAddress({
  rootAuthority: { ed25519: { publicKey: userPublicKey } },
  addressOptions: { accountIndex: 0 },
});
const walletAddress = reserved.wallet.walletAddress;
const swigConfigAddress = reserved.wallet.swigConfigAddress;

reserved = await swig.wallets.reserve_address(
    root_authority={"ed25519": {"public_key": user_public_key}},
    account_index=0,
)
wallet_address = reserved.wallet.wallet_address
swig_config_address = reserved.wallet.swig_config_address

use swig_developer_sdk::{
    ReservationAddressOptions, ReserveWalletAddressArgs, WalletAuthority,
};

let reserved = wallet.reserve_address(ReserveWalletAddressArgs {
    root_authority: WalletAuthority::Ed25519 { public_key: user_public_key },
    address_options: Some(ReservationAddressOptions::AccountIndex(0)),
}).await?;
let wallet_address = reserved.wallet.wallet_address;
let swig_config_address = reserved.wallet.swig_config_address;

walletAddress / wallet_address is the SOL deposit address and token-account owner. swigConfigAddress / swig_config_address identifies the wallet’s roles. Confirm that the selected network supports counterfactual creation before funding an address.

Create the reserved wallet

Use the same root authority and index or salt. The protocol initializes role 0 with that authority and All permission. A funded external fee payer signs the activation transaction; the root authority does not need to sign it.

const created = await swig.wallets.createReserved({
  rootAuthority: { ed25519: { publicKey: userPublicKey } },
  addressOptions: { accountIndex: 0 },
  feePayer,
});

created = await swig.wallets.create_reserved(
    root_authority={"ed25519": {"public_key": user_public_key}},
    account_index=0,
    fee_payer=fee_payer,
)

use swig_developer_sdk::{
    PrepareCreateReservedWalletArgs, ReservationAddressOptions, WalletAuthority,
};

let created = wallet.prepare_create_reserved_wallet(PrepareCreateReservedWalletArgs {
    root_authority: WalletAuthority::Ed25519 { public_key: user_public_key },
    address_options: Some(ReservationAddressOptions::AccountIndex(0)),
    fee_payer,
}).await?;

The result contains the reserved addresses and one prepared transaction: created.creationTransaction in TypeScript, created.creation_transaction in Python, or created.transaction in Rust. Sign with the fee payer, submit, and confirm through the existing Signing and Paymaster flow. Preparation records the create-wallet intent and prepared response, and counts toward API usage. Reusing the reservation preserves the address. Repeated on-chain activation preserves existing roles and balances; retain the original inputs after owner rotation. A closed wallet cannot be recreated from its reservation.

Flow

Choose creation path
  ├─ Authority / policy
  │   └─ Prepare creation
  └─ Reserve address
      └─ Prepare creation
Sign and submit
  └─ Confirm

Input

Parameter	Required	Description
`feePayer` / `fee_payer`	For creation	Public key paying transaction fees and account rent
`initialUser` / `initial_user`	For inline creation	Initial authority: Ed25519, secp256k1, or secp256r1 public key; also required when a saved policy asks for it
`policyId` / `policy_id`	No	Saved policy ID; omit for inline creation
`rootAuthority` / `root_authority`	For reservation and activation	Direct Ed25519, secp256k1, or secp256r1 public key; sessions and ParticipantSet roots are unsupported
Account index	No	Integer from `0` through `4294967295`; defaults to `0`. TypeScript: `addressOptions.accountIndex`; Python: `account_index`; Rust: `ReservationAddressOptions::AccountIndex`
Salt	Alternative to an index	Exactly 32 bytes. TypeScript: `addressOptions.salt` as `Uint8Array`; Python: `salt` as `bytes`; Rust: `ReservationAddressOptions::Salt([u8; 32])`. Supply either an index or a salt
`network`	Yes, on the call or client	`mainnet` or `devnet`; Rust uses its configured `Network`

TypeScript/Python use address strings. Rust uses Pubkey for Ed25519 and compressed 33-byte SEC1 keys for secp256k1/secp256r1. An application supplies passkey or EVM public keys; credential creation remains in your signing layer. Reservation and activation use rootAuthority / root_authority; inline or policy creation uses initialUser / initial_user. Reserved activation has a fixed root role and accepts no policy template.

Errors

Error	Meaning
Missing network or initial authority	Creation has no resolved network or the template needs an authority. Set the client network and supply the required initial authority.
Invalid public key	The key cannot be decoded or is invalid for its curve. Use the correct authority type; Rust secp256 keys must be compressed 33-byte SEC1 keys.
Unsupported creation plan in Rust	Ordinary wallet creation returned zero or multiple transactions. Use the TypeScript/Python ordered-plan flow for a multi-transaction creation. Reserved creation returns one transaction.
Invalid reservation options	The account index is outside the unsigned 32-bit range, the salt is not 32 bytes, or both are supplied. Reuse the same valid options for lookup and creation.
Invalid reserved-wallet response	The response has malformed addresses, a different network, an inconsistent transaction, or an unexpected transaction count or kind. Preparation has not submitted anything.
Request or preparation failed	The API request or a preparation dependency failed. Retrying the same reservation inputs derives the same addresses; each admitted request counts toward API usage.

Getting started

Wallet

Query

Finance

AI

Additional resources