Wallet - Crossmint Docs

Class

class Wallet

Instance Properties

Property	Type	Description
`address`	`String`	-
`recoveryMethods`	`[RecoveryMethod]`	Every recovery method of this wallet, with its install status. The list reflects the wallet at load time. `addRecoveryMethod(_:)` and `removeRecoveryMethod(locator:)` update it after a successful change.

Instance Methods

addRecoveryMethod(_:)

Adds a recovery method to the wallet.

@discardableResult func addRecoveryMethod(_ method: SignerConfig) async throws(WalletError) -> Transaction

Return Value

The completed Transaction.

Discussion

Solana and Stellar wallets only. A recovery method of the wallet approves the change. To select it, see useRecoveryMethod(_:).

Throws: WalletError.recoveryConfigRejected(code:message:) with one of these codes:

WalletError.RecoveryConfigCode.notSupportedOnChain if the wallet is an EVM wallet.

WalletError.RecoveryConfigCode.signerNotAllowed if method is a passkey and the wallet is a Solana wallet.

Example

let transaction = try await wallet.addRecoveryMethod(.email("backup@example.com"))

Parameters

Parameter	Description
`method`	An email, phone, external wallet or passkey signer. For a passkey, the SDK shows the system prompt to create a new passkey. A Solana wallet does not accept a passkey as a recovery method.

addSigner(_:)

Registers a new signer on this wallet.

func addSigner(_ config: SignerConfig) async throws(WalletError)

Discussion

Throws: WalletError if registration fails.

Parameters

Parameter	Description
`config`	The signer configuration to register.

approve(transactionId:)

Approves and submits a pending transaction on behalf of the current signer.

func approve(transactionId id: String) async throws(TransactionError) -> Transaction

Discussion

Use this when a transaction was created externally (e.g. via the Crossmint API) and shows TransactionStatus.awaitingApproval. The SDK signs the approval message and polls until the transaction reaches a terminal state.

Parameters

Parameter	Description
`id`	The transaction ID returned by the Crossmint API.

balance(of:)

func balance(of tokens: [CryptoCurrency] = []) async throws(WalletError) -> Balances

balances(_:_:)

Returns balances for the requested tokens, always including the chain’s native token and USDC.

func balances(_ tokens: [CryptoCurrency] = [], _ chains: [Chain] = []) async throws(WalletError) -> Balance

Parameters

Parameter	Description
`tokens`	Additional tokens to include. Native token and USDC are always fetched.
`chains`	Additional chains to query. The wallet’s own chain is always included.

fund(token:amount:)

Funds the wallet with test tokens from the Crossmint faucet.

func fund(token: CryptoCurrency, amount: Int) async throws(WalletError)

Discussion

Only available in staging/development environments; throws in production.

Parameters

Parameter	Description
`token`	The token to fund.
`amount`	Amount in the token’s smallest unit (e.g. lamports for SOL, wei for ETH).

getTransaction(id:)

Fetches a transaction by its ID.

func getTransaction(id: String) async throws(TransactionError) -> Transaction

Return Value

The Transaction matching the given ID.

Discussion

Use this to check the current status of a transaction, including its TransactionStatus, on-chain data, and any pending or submitted approvals.

Throws: TransactionError if the transaction cannot be retrieved or decoded.

Example

let transaction = try await wallet.getTransaction(id: "42bbb192-...")
if transaction.status == .success {
    print("Confirmed:", transaction.onChain.txId ?? "")
}

Parameters

Parameter	Description
`id`	The transaction ID returned by the Crossmint API.

isSignerApproved(_:)

Returns whether the given signer is approved and usable on this wallet’s chain.

func isSignerApproved(_ locator: String) async throws(WalletError) -> Bool

Discussion

A freshly registered signer can need approval before it can sign. Call addSigner(_:) to register a signer. This method returns false when the signer is not registered on this wallet.

Throws: WalletError if the request fails, or WalletError.signerLocatorError(_:) when the locator string does not parse as a SignerLocator.

Parameters

Parameter	Description
`locator`	A signer locator string, for example `"email:user@example.com"`, `"phone:+15551234567"`, `"device:<pubkey>"`, `"api-key"`, or `"passkey:<id>"`.

isSignerApproved(_:)

Returns whether the given signer is approved and usable on this wallet’s chain.

func isSignerApproved(_ locator: SignerLocator) async throws(WalletError) -> Bool

Discussion

A freshly registered signer can need approval before it can sign. Call addSigner(_:) to register a signer. This method returns false when the signer is not registered on this wallet.

Throws: WalletError if the request fails.

Parameters

Parameter	Description
`locator`	The locator of the signer to check.

listTransactions(page:transactionsPerPage:)

Fetches a page of the transaction history for this wallet, ordered most recent first.

func listTransactions(page: Int, transactionsPerPage: Int) async throws(TransactionError) -> [Transaction]

Return Value

The wallet’s Transaction list for the requested page.

Discussion

Throws: TransactionError if the request fails.

Example

let transactions = try await wallet.listTransactions(page: 1, transactionsPerPage: 20)

for transaction in transactions {
    print("\(transaction.id): \(transaction.status)")
}

Parameters

Parameter	Description
`page`	One-based page index.
`transactionsPerPage`	Number of transactions per page.

listTransfers(tokens:)

Fetches the transfer history for this wallet.

func listTransfers(tokens: [CryptoCurrency]) async throws(WalletError) -> TransferListResult

Return Value

A TransferListResult containing the transfer events sorted by timestamp (most recent first).

Discussion

Returns a list of incoming and outgoing transfers for the specified tokens. Use this method to display transaction history in your application.

Throws: WalletError if the request fails.

Example

// Fetch ETH and USDC transfers
let result = try await wallet.listTransfers(tokens: [.eth, .usdc])

for transfer in result.transfers {
    switch transfer.type {
    case .outgoing:
        print("Sent \(transfer.amount) \(transfer.tokenSymbol ?? "tokens")")
    case .incoming:
        print("Received \(transfer.amount) \(transfer.tokenSymbol ?? "tokens")")
    case .unknown:
        break
    }
}

Parameters

Parameter	Description
`tokens`	The cryptocurrency tokens to fetch transfers for. Common values include `.eth`, `.usdc`, `.sol`, etc.

localDeviceSigner()

Returns the locator of the device signer whose private key is on this device. Returns nil if this wallet has no such signer.

func localDeviceSigner() async -> SignerLocator?

Discussion

A wallet can have device: delegated signers registered from other devices. This method only returns a locator when the matching key is present in local secure storage.

localDeviceSignerLocator()

Returns the locator string of the device signer whose private key is on this device. Returns nil if this wallet has no such signer.

func localDeviceSignerLocator() async -> String?

needsRecovery()

Returns whether this wallet needs recovery on the current device.

func needsRecovery() async -> Bool

Discussion

A wallet needs recovery when a device signer is configured but the signing key for this wallet is not present on the current device. Call recover() to re-register.

Note: This method awaits the background signer-initialization task that runs at wallet creation, so the first call may take a moment on slow networks.

nfts(page:nftsPerPage:)

Returns a page of NFTs owned by this wallet.

func nfts(page: Int, nftsPerPage: Int) async throws(WalletError) -> [NFT]

Parameters

Parameter	Description
`page`	Zero-based page index.
`nftsPerPage`	Number of NFTs per page.

recover()

Re-registers the device signer on this device.

func recover() async throws(WalletError)

Discussion

Call this when needsRecovery() returns true — i.e. the wallet has a device signer registered but the private key is missing on the current device. This generates a new key, registers it with Crossmint, and awaits approval from the existing admin signer. If the wallet’s provider does not support device signers, this returns without error and signing stays on the recovery signer; the rejection is remembered so registration is not retried for this wallet instance.

Throws: WalletError if recovery fails or there is no device signer configured.

removeRecoveryMethod(locator:)

Removes a recovery method from the wallet.

@discardableResult func removeRecoveryMethod(locator: SignerLocator) async throws(WalletError) -> Transaction

Return Value

The completed Transaction.

Discussion

Solana and Stellar wallets only. A different recovery method of the wallet approves the change. To select it, see useRecoveryMethod(_:). If you selected the removed recovery method, the SDK clears the selection. To remove a signer that you added with addSigner(_:), use removeSigner(locator:).

Throws: WalletError.recoveryConfigRejected(code:message:) with one of these codes:

WalletError.RecoveryConfigCode.notSupportedOnChain on an EVM wallet.

WalletError.RecoveryConfigCode.lastSigner if the wallet has no other recovery method.

Example

let transaction = try await wallet.removeRecoveryMethod(locator: .email("old@example.com"))

Parameters

Parameter	Description
`locator`	The recovery method to remove.

removeSigner(locator:)

Removes an assigned signer from this wallet.

func removeSigner(locator: String) async throws(TransactionError) -> Transaction

Return Value

The completed Transaction once the signer has been removed on-chain.

Discussion

This method submits a remove-signer transaction on-chain. If the transaction needs approval, the current signer signs it. The method then polls until the transaction completes.

Parameters

Parameter	Description
`locator`	The signer locator string that identifies the signer to remove, for example `"device:ABC123..."` or `"external-wallet:0x456..."`.

removeSigner(locator:)

Removes an assigned signer from this wallet.

func removeSigner(locator: SignerLocator) async throws(TransactionError) -> Transaction

Return Value

The completed Transaction once the signer has been removed on-chain.

Discussion

This method submits a remove-signer transaction on-chain. If the transaction needs approval, the current signer signs it. The method then polls until the transaction completes. Use removeRecoveryMethod(locator:) to remove a recovery method.

Parameters

Parameter	Description
`locator`	The locator that identifies the signer to remove.

send(_:_:_:idempotencyKey:)

Transfers tokens to another wallet and polls until the transaction is confirmed on-chain.

func send(_ walletLocator: String, _ tokenLocator: String, _ amount: Double, idempotencyKey: String? = nil) async throws(TransactionError) -> TransactionSummary

Return Value

A TransactionSummary with the on-chain hash and explorer link once confirmed.

Example

let summary = try await wallet.send(
    "0xRecipient...",
    "base-sepolia:usdc",
    5.0
)
print("Sent. Explorer:", summary.explorerLink)

Parameters

Parameter	Description
`walletLocator`	Recipient address (e.g. `"0xABC..."` or a Solana public key).
`tokenLocator`	`"{chain}:{token}"`, e.g. `"base-sepolia:eth"` or `"solana:usdc"`.
`amount`	Amount as a human-readable decimal (e.g. `0.01` for 0.01 ETH).
`idempotencyKey`	Pass a stable key to prevent duplicate transactions on retry; omit to generate one automatically.

send(token:recipient:amount:)

func send(token: CryptoCurrency, recipient: TransferTokenRecipient, amount: String) async throws(TransactionError) -> Transaction

signerIsRegistered(_:)

Returns true if the locator is a signer on this wallet.

func signerIsRegistered(_ locator: SignerLocator) async -> Bool

Discussion

This method sends a request to the server. It returns false if the request fails.

signerIsRegistered(_:)

Returns true if the locator is a signer on this wallet.

func signerIsRegistered(_ locator: String) async -> Bool

Discussion

This method sends a request to the server. It returns false if the request fails. It also returns false if the locator string is not valid.

Parameters

Parameter	Description
`locator`	A signer locator string, for example `"email:user@example.com"`, `"phone:+15551234567"`, `"device:<pubkey>"`, `"api-key"`, or `"passkey:<id>"`.

signers()

Fetches the current list of signers from the API.

func signers() async throws(WalletError) -> [WalletSigner]

Discussion

Each WalletSigner includes its registration status on this wallet’s chain. On EVM wallets, signers without a registration entry (pending or completed) for the wallet’s chain are omitted. A signer whose state lookup fails is returned with SignerStatus.unknown rather than dropped. Always returns fresh data — safe to call after addSigner(_:) or removeSigner(locator:).

transferToken(tokenId:recipient:amount:)

Transfers an NFT or fungible token to a recipient.

func transferToken(tokenId: String? = nil, recipient: TransferTokenRecipient, amount: String) async throws(TransactionError) -> Transaction

Parameters

Parameter	Description
`tokenId`	NFT token ID to transfer; omit for fungible token transfers.
`recipient`	Recipient address or wallet locator.
`amount`	Amount as a string (e.g. `"1"` for one NFT, or a fungible amount).

useRecoveryMethod(_:)

Selects the recovery method that approves changes to signers and recovery methods.

func useRecoveryMethod(_ method: SignerConfig) async throws(WalletError)

Discussion

The signer for transactions and messages does not change. To change it, use useSigner(_:). If you do not select a recovery method, the SDK uses one of these:

The only recovery method of the wallet.
The active signer, if it is a recovery method. If neither applies, the change fails with WalletError.RecoveryConfigCode.signerRequired.

Throws: WalletError.recoveryConfigRejected(code:message:) with WalletError.RecoveryConfigCode.invalidConfig if method is not in recoveryMethods, or if method is a passkey with no id and the wallet has more than one passkey recovery method. The SDK throws WalletError.walletGeneric(_:) for a different signer type.

Example

try await wallet.useRecoveryMethod(.phone("+14155552671"))
let transaction = try await wallet.removeRecoveryMethod(locator: .email("old@example.com"))

Parameters

Parameter	Description
`method`	An email, phone, API key or passkey recovery method of the wallet. For a passkey, the SDK selects the passkey in `recoveryMethods` that has the `id` you give. If `id` is `nil`, the wallet must have only one passkey recovery method. The SDK does not create a new passkey.

useSigner(_:)

Sets the signer for the send and sign operations of this wallet.

func useSigner(_ config: SignerConfig) async throws(WalletError)

Discussion

The signer replaces the admin signer. The signer must be registered on this wallet. To register a new signer, call addSigner(_:) first. To select the recovery method that approves signer changes, use useRecoveryMethod(_:).

Throws: - WalletError.signerNotRegistered(_:) if the signer is not registered on this wallet.

The WalletError of the failed request if the API does not return the wallet signers. The active signer does not change. You can try again.

WalletError.walletGeneric(_:) if config is SignerConfig.externalWallet(_:onSign:) and onSign is nil.

WalletError.walletGeneric(_:) if config is SignerConfig.passkey(name:host:id:) with no id and the wallet has more than one passkey signer.

WalletError.deviceSignerNotSupported(_:) if you select .device and the wallet provider does not accept device signers.

Parameters

Parameter	Description
`config`	The signer to use.

​Instance Properties

​Instance Methods

​addRecoveryMethod(_:)

​Return Value

​Discussion

​Example

​Parameters

​addSigner(_:)

​Discussion

​Parameters

​approve(transactionId:)

​Discussion

​Parameters

​balance(of:)

​balances(_:_:)

​Parameters

​fund(token:amount:)

​Discussion

​Parameters

​getTransaction(id:)

​Return Value

​Discussion

​Example

​Parameters

​isSignerApproved(_:)

​Discussion

​Parameters

​isSignerApproved(_:)

​Discussion

​Parameters

​listTransactions(page:transactionsPerPage:)

​Return Value

​Discussion

​Example

​Parameters

​listTransfers(tokens:)

​Return Value

​Discussion

​Example

​Parameters

​localDeviceSigner()

​Discussion

​localDeviceSignerLocator()

​needsRecovery()

​Discussion

​nfts(page:nftsPerPage:)

​Parameters

​recover()

​Discussion

​removeRecoveryMethod(locator:)

​Return Value

​Discussion

​Example

​Parameters

​removeSigner(locator:)

​Return Value

​Discussion

​Parameters

​removeSigner(locator:)

​Return Value

​Discussion

​Parameters

​send(_:_:_:idempotencyKey:)

​Return Value

​Example

​Parameters

​send(token:recipient:amount:)

​signerIsRegistered(_:)

​Discussion

​signerIsRegistered(_:)

​Discussion

​Parameters

​signers()

​Discussion

​transferToken(tokenId:recipient:amount:)

​Parameters

​useRecoveryMethod(_:)

​Discussion

​Example

​Parameters

Instance Properties

Instance Methods

addRecoveryMethod(_:)

Return Value

Discussion

Example

Parameters

addSigner(_:)

Discussion

Parameters

approve(transactionId:)

Discussion

Parameters

balance(of:)

balances(_:_:)

Parameters

fund(token:amount:)

Discussion

Parameters

getTransaction(id:)

Return Value

Discussion

Example

Parameters

isSignerApproved(_:)

Discussion

Parameters

isSignerApproved(_:)

Discussion

Parameters

listTransactions(page:transactionsPerPage:)

Return Value

Discussion

Example

Parameters

listTransfers(tokens:)

Return Value

Discussion

Example

Parameters

localDeviceSigner()

Discussion

localDeviceSignerLocator()

needsRecovery()

Discussion

nfts(page:nftsPerPage:)

Parameters

recover()

Discussion

removeRecoveryMethod(locator:)

Return Value

Discussion

Example

Parameters

removeSigner(locator:)

Return Value

Discussion

Parameters

removeSigner(locator:)

Return Value

Discussion

Parameters

send(_:_:_:idempotencyKey:)

Return Value

Example

Parameters

send(token:recipient:amount:)

signerIsRegistered(_:)

Discussion

signerIsRegistered(_:)

Discussion

Parameters

signers()

Discussion

transferToken(tokenId:recipient:amount:)

Parameters

useRecoveryMethod(_:)

Discussion

Example

Parameters