viem

SettleMint SDK

✨ https://settlemint.com ✨
Integrate SettleMint into your application with ease.

Documentation   •   NPM   •   Issues

Table of Contents

• About
• API Reference
  • Functions
    • getChainId()
    • getPublicClient()
    • getWalletClient()
  • Enumerations
    • OTPAlgorithm
    • WalletVerificationType
  • Interfaces
    • CreateWalletParameters
    • CreateWalletResponse
    • CreateWalletVerificationChallengeParameters
    • CreateWalletVerificationChallengesParameters
    • CreateWalletVerificationParameters
    • CreateWalletVerificationResponse
    • DeleteWalletVerificationParameters
    • DeleteWalletVerificationResponse
    • GetWalletVerificationsParameters
    • VerificationResult
    • VerifyWalletVerificationChallengeParameters
    • WalletInfo
    • WalletOTPVerificationInfo
    • WalletPincodeVerificationInfo
    • WalletSecretCodesVerificationInfo
    • WalletVerification
    • WalletVerificationChallenge
    • WalletVerificationChallengeData
    • WalletVerificationOptions
  • Type Aliases
    • AddressOrObject
    • AddressOrObjectWithChallengeId
    • ClientOptions
    • CreateWalletVerificationChallengeResponse
    • CreateWalletVerificationChallengesResponse
    • GetChainIdOptions
    • GetWalletVerificationsResponse
    • VerifyWalletVerificationChallengeResponse
    • WalletVerificationInfo
  • Variables
    • ClientOptionsSchema
    • GetChainIdOptionsSchema
• Contributing
• License

About

The SettleMint Viem SDK provides a lightweight wrapper that automatically configures and sets up a Viem client based on your connected SettleMint application. It simplifies the process of establishing connections to SettleMint-managed blockchain networks by handling authentication, endpoint configuration, and chain selection. This allows developers to quickly start using Viem's powerful Ethereum interaction capabilities without manual setup, while ensuring proper integration with the SettleMint platform.

API Reference

Functions

getChainId()

getChainId(options): Promise<number>

Defined in: sdk/viem/src/viem.ts:456

Discovers the chain ID from an RPC endpoint without requiring prior knowledge.

Parameters

Parameter	Type	Description
options	GetChainIdOptions	Minimal options with RPC URL and optional authentication

Returns

Promise<number>

Promise resolving to the network's chain ID as a number

Remarks

UTILITY: Enables chain discovery for dynamic network configuration scenarios. Unlike other client functions, this creates a minimal, non-cached client for one-time queries.

USE CASE: Chain ID discovery during initial network setup or validation. Alternative to requiring users to know chain IDs in advance.

PERFORMANCE: No caching because chain IDs are typically discovered once during setup rather than repeatedly during runtime operations.

Throws

NetworkError when RPC endpoint is unreachable

Throws

AuthenticationError when access token is invalid

Example

import { getChainId } from '@settlemint/sdk-viem';

const chainId = await getChainId({
  accessToken: process.env.SETTLEMINT_ACCESS_TOKEN,
  rpcUrl: process.env.SETTLEMINT_BLOCKCHAIN_NODE_OR_LOAD_BALANCER_JSON_RPC_ENDPOINT!,
});
console.log(chainId);

---

getPublicClient()

getPublicClient(options): Client<HttpTransport<RpcSchema | undefined, boolean>, Chain, undefined, PublicRpcSchema, object & PublicActions<HttpTransport<RpcSchema | undefined, boolean>, Chain>>

Defined in: sdk/viem/src/viem.ts:201

Creates an optimized public client for blockchain read operations.

Parameters

Parameter	Type	Description
options	ClientOptions	Client configuration including chain details and authentication

Returns

Client<HttpTransport<RpcSchema | undefined, boolean>, Chain, undefined, PublicRpcSchema, object & PublicActions<HttpTransport<RpcSchema | undefined, boolean>, Chain>>

Cached or newly created public client with read-only blockchain access

Remarks

PERFORMANCE: Implements intelligent caching to minimize client creation overhead. Cache hit rates of 80%+ typical in production workloads with repeated chain access.

SECURITY: Each access token gets isolated cache entries to prevent cross-tenant data exposure. Client instances are immutable once cached to prevent credential pollution.

RESOURCE MANAGEMENT: 500ms polling interval balances responsiveness with server load. 60-second timeout prevents hanging connections in unstable network conditions.

Throws

ValidationError when options don't match required schema

Throws

NetworkError when RPC endpoint is unreachable during client creation

Example

import { getPublicClient } from '@settlemint/sdk-viem';

const publicClient = getPublicClient({
  accessToken: process.env.SETTLEMINT_ACCESS_TOKEN,
  chainId: process.env.SETTLEMINT_BLOCKCHAIN_NETWORK_CHAIN_ID!,
  chainName: process.env.SETTLEMINT_BLOCKCHAIN_NETWORK!,
  rpcUrl: process.env.SETTLEMINT_BLOCKCHAIN_NODE_OR_LOAD_BALANCER_JSON_RPC_ENDPOINT!,
});

// Get the block number
const block = await publicClient.getBlockNumber();
console.log(block);

---

getWalletClient()

getWalletClient(options): (verificationOptions?) => Client<HttpTransport<RpcSchema | undefined, boolean>>

Defined in: sdk/viem/src/viem.ts:323

Creates a factory function for wallet clients with runtime verification support.

Parameters

Parameter	Type	Description
options	ClientOptions	Base client configuration (chain, RPC, auth)

Returns

Factory function that accepts runtime verification options

(verificationOptions?): Client<HttpTransport<RpcSchema | undefined, boolean>>

Parameters

Parameter	Type
verificationOptions?	WalletVerificationOptions

Returns

Client<HttpTransport<RpcSchema | undefined, boolean>>

Remarks

DESIGN PATTERN: Returns a factory function rather than a client instance because wallet operations require runtime verification parameters (challenge responses, etc.) that cannot be known at factory creation time.

SECURITY: Verification headers are injected per-operation to support:

• HD wallet challenge/response flows
• Multi-signature verification workflows
• Time-sensitive authentication tokens

PERFORMANCE: Factory caching amortizes expensive setup (chain resolution, transport config) while allowing runtime parameter injection for each wallet operation.

FEATURE EXTENSIONS: Automatically extends client with SettleMint-specific wallet actions:

• Wallet creation and management
• Verification challenge handling
• Multi-factor authentication flows

Throws

ValidationError when options don't match required schema

Example

import { getWalletClient } from '@settlemint/sdk-viem';
import { parseAbi } from "viem";

const walletClient = getWalletClient({
  accessToken: process.env.SETTLEMINT_ACCESS_TOKEN,
  chainId: process.env.SETTLEMINT_BLOCKCHAIN_NETWORK_CHAIN_ID!,
  chainName: process.env.SETTLEMINT_BLOCKCHAIN_NETWORK!,
  rpcUrl: process.env.SETTLEMINT_BLOCKCHAIN_NODE_OR_LOAD_BALANCER_JSON_RPC_ENDPOINT!,
});

// Get the chain id
const chainId = await walletClient().getChainId();
console.log(chainId);

// write to the blockchain
const transactionHash = await walletClient().writeContract({
  account: "0x0000000000000000000000000000000000000000",
  address: "0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2",
  abi: parseAbi(["function mint(uint32 tokenId) nonpayable"]),
  functionName: "mint",
  args: [69420],
});
console.log(transactionHash);

Enumerations

OTPAlgorithm

Defined in: sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:18

Supported hash algorithms for One-Time Password (OTP) verification. These algorithms determine the cryptographic function used to generate OTP codes.

Enumeration Members

Enumeration Member	Value	Description	Defined in
SHA1	"SHA1"	SHA-1 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:20
SHA224	"SHA224"	SHA-224 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:22
SHA256	"SHA256"	SHA-256 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:24
SHA3_224	"SHA3-224"	SHA3-224 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:30
SHA3_256	"SHA3-256"	SHA3-256 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:32
SHA3_384	"SHA3-384"	SHA3-384 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:34
SHA3_512	"SHA3-512"	SHA3-512 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:36
SHA384	"SHA384"	SHA-384 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:26
SHA512	"SHA512"	SHA-512 hash algorithm	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:28

---

WalletVerificationType

Defined in: sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:5

Types of wallet verification methods supported by the system. Used to identify different verification mechanisms when creating or managing wallet verifications.

Enumeration Members

Enumeration Member	Value	Description	Defined in
OTP	"OTP"	One-Time Password verification method	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:9
PINCODE	"PINCODE"	PIN code verification method	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:7
SECRET_CODES	"SECRET_CODES"	Secret recovery codes verification method	sdk/viem/src/custom-actions/types/wallet-verification.enum.ts:11

Interfaces

CreateWalletParameters

Defined in: sdk/viem/src/custom-actions/create-wallet.action.ts:16

Parameters for creating a wallet.

Properties

Property	Type	Description	Defined in
keyVaultId	string	The unique name of the key vault where the wallet will be created.	sdk/viem/src/custom-actions/create-wallet.action.ts:18
walletInfo	WalletInfo	Information about the wallet to be created.	sdk/viem/src/custom-actions/create-wallet.action.ts:20

---

CreateWalletResponse

Defined in: sdk/viem/src/custom-actions/create-wallet.action.ts:26

Response from creating a wallet.

Properties

Property	Type	Description	Defined in
address	string	The blockchain address of the wallet.	sdk/viem/src/custom-actions/create-wallet.action.ts:32
derivationPath	string	The HD derivation path used to create the wallet.	sdk/viem/src/custom-actions/create-wallet.action.ts:34
id	string	The unique identifier of the wallet.	sdk/viem/src/custom-actions/create-wallet.action.ts:28
name	string	The name of the wallet.	sdk/viem/src/custom-actions/create-wallet.action.ts:30

---

CreateWalletVerificationChallengeParameters

Defined in: sdk/viem/src/custom-actions/create-wallet-verification-challenge.action.ts:7

Parameters for creating wallet verification challenges.

Properties

Property	Type	Description	Defined in
userWalletAddress	string	The wallet address.	sdk/viem/src/custom-actions/create-wallet-verification-challenge.action.ts:9
verificationId	string	The verification ID.	sdk/viem/src/custom-actions/create-wallet-verification-challenge.action.ts:11

---

CreateWalletVerificationChallengesParameters

Defined in: sdk/viem/src/custom-actions/create-wallet-verification-challenges.action.ts:8

Parameters for creating wallet verification challenges.

Properties

Property	Type	Description	Defined in
addressOrObject	AddressOrObject<{ amount?: number; }>	The wallet address or object containing wallet address and optional verification ID.	sdk/viem/src/custom-actions/create-wallet-verification-challenges.action.ts:10

---

CreateWalletVerificationParameters

Defined in: sdk/viem/src/custom-actions/create-wallet-verification.action.ts:59

Parameters for creating a wallet verification.

Properties

Property	Type	Description	Defined in
userWalletAddress	string	The wallet address for which to create the verification.	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:61
walletVerificationInfo	WalletVerificationInfo	The verification information to create.	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:63

---

CreateWalletVerificationResponse

Defined in: sdk/viem/src/custom-actions/create-wallet-verification.action.ts:69

Response from creating a wallet verification.

Properties

Property	Type	Description	Defined in
id	string	The unique identifier of the verification.	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:71
name	string	The name of the verification method.	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:73
parameters	Record<string, string>	Additional parameters specific to the verification type.	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:77
verificationType	WalletVerificationType	The type of verification method.	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:75

---

DeleteWalletVerificationParameters

Defined in: sdk/viem/src/custom-actions/delete-wallet-verification.action.ts:6

Parameters for deleting a wallet verification.

Properties

Property	Type	Description	Defined in
userWalletAddress	string	The wallet address for which to delete the verification.	sdk/viem/src/custom-actions/delete-wallet-verification.action.ts:8
verificationId	string	The unique identifier of the verification to delete.	sdk/viem/src/custom-actions/delete-wallet-verification.action.ts:10

---

DeleteWalletVerificationResponse

Defined in: sdk/viem/src/custom-actions/delete-wallet-verification.action.ts:16

Response from deleting a wallet verification.

Properties

Property	Type	Description	Defined in
success	boolean	Whether the deletion was successful.	sdk/viem/src/custom-actions/delete-wallet-verification.action.ts:18

---

GetWalletVerificationsParameters

Defined in: sdk/viem/src/custom-actions/get-wallet-verifications.action.ts:7

Parameters for getting wallet verifications.

Properties

Property	Type	Description	Defined in
userWalletAddress	string	The wallet address for which to fetch verifications.	sdk/viem/src/custom-actions/get-wallet-verifications.action.ts:9

---

VerificationResult

Defined in: sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:38

Result of a wallet verification challenge.

Properties

Property	Type	Description	Defined in
verified	boolean	Whether the verification was successful.	sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:40

---

VerifyWalletVerificationChallengeParameters

Defined in: sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:28

Parameters for verifying a wallet verification challenge.

Properties

Property	Type	Description	Defined in
addressOrObject	AddressOrObjectWithChallengeId	The wallet address or object containing wallet address and optional verification ID.	sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:30
challengeResponse	string	The response to the verification challenge.	sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:32

---

WalletInfo

Defined in: sdk/viem/src/custom-actions/create-wallet.action.ts:6

Information about the wallet to be created.

Properties

Property	Type	Description	Defined in
name	string	The name of the wallet.	sdk/viem/src/custom-actions/create-wallet.action.ts:8
walletIndex?	number	Optional index for the wallet, walletIndex enables HD derivation paths	sdk/viem/src/custom-actions/create-wallet.action.ts:10

---

WalletOTPVerificationInfo

Defined in: sdk/viem/src/custom-actions/create-wallet-verification.action.ts:27

Information for One-Time Password (OTP) verification.

Extends

• BaseWalletVerificationInfo

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
algorithm?	OTPAlgorithm	The hash algorithm to use for OTP generation.	-	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:31
digits?	number	The number of digits in the OTP code.	-	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:33
issuer?	string	The issuer of the OTP.	-	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:37
name	string	The name of the verification method.	-	BaseWalletVerificationInfo.name	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:9
period?	number	The time period in seconds for OTP validity.	-	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:35
verificationType	OTP	The type of verification method.	BaseWalletVerificationInfo.verificationType	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:29

---

WalletPincodeVerificationInfo

Defined in: sdk/viem/src/custom-actions/create-wallet-verification.action.ts:17

Information for PIN code verification.

Extends

• BaseWalletVerificationInfo

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
name	string	The name of the verification method.	-	BaseWalletVerificationInfo.name	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:9
pincode	string	The PIN code to use for verification.	-	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:21
verificationType	PINCODE	The type of verification method.	BaseWalletVerificationInfo.verificationType	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:19

---

WalletSecretCodesVerificationInfo

Defined in: sdk/viem/src/custom-actions/create-wallet-verification.action.ts:43

Information for secret recovery codes verification.

Extends

• BaseWalletVerificationInfo

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
name	string	The name of the verification method.	-	BaseWalletVerificationInfo.name	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:9
verificationType	SECRET_CODES	The type of verification method.	BaseWalletVerificationInfo.verificationType	-	sdk/viem/src/custom-actions/create-wallet-verification.action.ts:45

---

WalletVerification

Defined in: sdk/viem/src/custom-actions/get-wallet-verifications.action.ts:15

Represents a wallet verification.

Properties

Property	Type	Description	Defined in
id	string	The unique identifier of the verification.	sdk/viem/src/custom-actions/get-wallet-verifications.action.ts:17
name	string	The name of the verification method.	sdk/viem/src/custom-actions/get-wallet-verifications.action.ts:19
verificationType	WalletVerificationType	The type of verification method.	sdk/viem/src/custom-actions/get-wallet-verifications.action.ts:21

---

WalletVerificationChallenge

Defined in: sdk/viem/src/custom-actions/types/wallet-verification-challenge.ts:6

Represents a wallet verification challenge.

Type Parameters

Type Parameter
ChallengeData

Properties

Property	Type	Description	Defined in
challenge	ChallengeData	The challenge parameters specific to the verification type.	sdk/viem/src/custom-actions/types/wallet-verification-challenge.ts:16
id	string	The unique identifier of the challenge.	sdk/viem/src/custom-actions/types/wallet-verification-challenge.ts:8
name	string	The name of the challenge.	sdk/viem/src/custom-actions/types/wallet-verification-challenge.ts:10
verificationId	string	The verification ID.	sdk/viem/src/custom-actions/types/wallet-verification-challenge.ts:12
verificationType	WalletVerificationType	The type of verification required.	sdk/viem/src/custom-actions/types/wallet-verification-challenge.ts:14

---

WalletVerificationChallengeData

Defined in: sdk/viem/src/custom-actions/create-wallet-verification-challenge.action.ts:17

Data specific to a wallet verification challenge.

Properties

Property	Type	Description	Defined in
salt?	string	Optional salt for PINCODE verification type.	sdk/viem/src/custom-actions/create-wallet-verification-challenge.action.ts:19
secret?	string	Optional secret for PINCODE verification type.	sdk/viem/src/custom-actions/create-wallet-verification-challenge.action.ts:21

---

WalletVerificationOptions

Defined in: sdk/viem/src/viem.ts:256

The options for the wallet client.

Properties

Property	Type	Description	Defined in
challengeId?	string	The challenge id (used for HD wallets)	sdk/viem/src/viem.ts:264
challengeResponse	string	The challenge response (used for HD wallets)	sdk/viem/src/viem.ts:268
verificationId?	string	The verification id (used for HD wallets), if not provided, the challenge response will be validated against all active verifications.	sdk/viem/src/viem.ts:260

Type Aliases

AddressOrObject

AddressOrObject<Extra> = string | object & Extra

Defined in: sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:8

Represents either a wallet address string or an object containing wallet address and optional verification ID.

Type Parameters

Type Parameter	Default type
Extra	object

---

AddressOrObjectWithChallengeId

AddressOrObjectWithChallengeId = AddressOrObject | { challengeId: string; }

Defined in: sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:18

Represents either a wallet address string, an object containing wallet address and optional verification ID or a challenge ID.

Type Declaration

AddressOrObject

{ challengeId: string; }

Name	Type	Description	Defined in
challengeId	string	ID of the challenge to verify against	sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:22

---

ClientOptions

ClientOptions = Omit<z.infer<typeof ClientOptionsSchema>, "httpTransportConfig"> & object

Defined in: sdk/viem/src/viem.ts:163

Type representing the validated client options.

Type Declaration

Name	Type	Defined in
httpTransportConfig?	HttpTransportConfig	sdk/viem/src/viem.ts:164

---

CreateWalletVerificationChallengeResponse

CreateWalletVerificationChallengeResponse = WalletVerificationChallenge<WalletVerificationChallengeData>

Defined in: sdk/viem/src/custom-actions/create-wallet-verification-challenge.action.ts:27

Response from creating wallet verification challenge.

---

CreateWalletVerificationChallengesResponse

CreateWalletVerificationChallengesResponse = Omit<WalletVerificationChallenge<Record<string, string>>, "verificationId">[]

Defined in: sdk/viem/src/custom-actions/create-wallet-verification-challenges.action.ts:16

Response from creating wallet verification challenges.

---

GetChainIdOptions

GetChainIdOptions = Omit<z.infer<typeof GetChainIdOptionsSchema>, "httpTransportConfig"> & object

Defined in: sdk/viem/src/viem.ts:423

Type representing the validated get chain id options.

Type Declaration

Name	Type	Defined in
httpTransportConfig?	HttpTransportConfig	sdk/viem/src/viem.ts:424

---

GetWalletVerificationsResponse

GetWalletVerificationsResponse = WalletVerification[]

Defined in: sdk/viem/src/custom-actions/get-wallet-verifications.action.ts:27

Response from getting wallet verifications.

---

VerifyWalletVerificationChallengeResponse

VerifyWalletVerificationChallengeResponse = VerificationResult[]

Defined in: sdk/viem/src/custom-actions/verify-wallet-verification-challenge.action.ts:46

Response from verifying a wallet verification challenge.

---

WalletVerificationInfo

WalletVerificationInfo = WalletPincodeVerificationInfo | WalletOTPVerificationInfo | WalletSecretCodesVerificationInfo

Defined in: sdk/viem/src/custom-actions/create-wallet-verification.action.ts:51

Union type of all possible wallet verification information types.

Variables

ClientOptionsSchema

const ClientOptionsSchema: ZodObject<{ accessToken: ZodOptional<ZodString>; chainId: ZodString; chainName: ZodString; httpTransportConfig: ZodOptional<ZodAny>; rpcUrl: ZodUnion<readonly [ZodString, ZodString]>; }, $strip>

Defined in: sdk/viem/src/viem.ts:137

Schema for the viem client options.

---

GetChainIdOptionsSchema

const GetChainIdOptionsSchema: ZodObject<{ accessToken: ZodOptional<ZodString>; httpTransportConfig: ZodOptional<ZodAny>; rpcUrl: ZodUnion<readonly [ZodString, ZodString]>; }, $strip>

Defined in: sdk/viem/src/viem.ts:405

Schema for the viem client options.

Contributing

We welcome contributions from the community! Please check out our Contributing guide to learn how you can help improve the SettleMint SDK through bug reports, feature requests, documentation updates, or code contributions.

License

The SettleMint SDK is released under the FSL Software License. See the LICENSE file for more details.