> ## Documentation Index > Fetch the complete documentation index at: https://uasdev.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Web (JS/TS): Universal Accounts SDK > Implementing Universal Accounts in your application. The **Universal Accounts SDK** provides **chain abstraction** for your app by integrating Universal Accounts. These, in turn, offer your users a single account, balance, and interaction point across **EVM chains** and **Solana**. Our SDK seamlessly integrates with your existing connection flow, with minimal setup. What are Universal Accounts, how do they work, and what problems do they solve? To integrate Universal Accounts: The following examples use a React-based app alongside [**Particle Auth**](/api-reference/auth/introduction) for authentication and wallet connection. However, the **Universal Accounts SDK is provider-agnostic**—alongside it, you can also use [**Particle Connect**](/api-reference/connect/introduction), **Web3Modal**, **RainbowKit**, or any **signer**. You can also use the SDK to construct and sign transactions programmatically on the server side. A user logs into their account by connecting a wallet or via a social login. Once connected, pass the user's EOA address to the SDK and configure your project's details. Use the returned Universal Account instance to fetch data and send transactions across chains. When sending a transaction, the SDK will create a **UserOperation** and return a `rootHash`. This hash must be **signed by the connected EOA**, then passed back into `sendTransaction()` to broadcast. Under the hood, all routing, bridging, and gas abstraction will be handled by Particle Network's infrastructure. *** ## Getting Started ### Installation Once your app is set up, install the **Universal Accounts SDK**: The SDK depends on `ethers.js` internally, but you’re not required to use it in your application. You can use any provider or signer logic that fits your setup. ```bash yarn theme={null} yarn add @particle-network/universal-account-sdk ethers ``` ```bash npm theme={null} npm install @particle-network/universal-account-sdk ethers ``` ### Import and Configure You can access and import the `UniversalAccount` class in your app from `@particle-network/universal-account-sdk`: ```tsx theme={null} import { UniversalAccount } from "@particle-network/universal-account-sdk"; ``` Then, initialize the UA instance once a user has connected: You need a **Universal Account Project ID (API key)** to initialize the SDK. Contact the Particle team to get an Access Key. ```tsx theme={null} const ua = new UniversalAccount({ projectId: "YOUR_UA_PROJECT_ID", // Replace with your actual key ownerAddress: "USERS_EOA_ADDRESS", // The user’s EOA address tradeConfig: { slippageBps: 100, // Optional: 100 = 1% slippage tolerance universalGas: true // Optional: let user pay gas in PARTI token }, }); ``` You can now use the `ua` instance to **fetch data** (a Universal Account's balance or addresses) and send **transactions**. Repository of sample Next.js app with social logins via Particle Auth + UA. ## Get a Universal Account's Addresses A **Universal Account** is composed of multiple addresses, each relevant to a specific interaction layer: 1. **Owner Address**: The EOA that owns the Universal Account and signs transactions (e.g., from MetaMask or via a social login). 2. **EVM Universal Address**: The **UA** address used on EVM-compatible chains. 3. **Solana Universal Address**: The **UA** address used on Solana. The EVM and Solana Universal Addresses are distinct due to the way deposits work on each network. You can deposit any **EVM token** to the **EVM Universal Address**, and any **Solana token** to the **Solana Universal Address**. EVM and Solana assets will be accessible through the **same UA instance**, and balance lookups and transactions will remain unified at the SDK level. You can retrieve all relevant addresses from an initialized Universal Account instance as follows: ```ts theme={null} const smartAccountOptions = await ua.getSmartAccountOptions(); const accountInfo = { ownerAddress: smartAccountOptions.ownerAddress, // EOA that owns the Universal Account evmUaAddress: smartAccountOptions.smartAccountAddress!, // EVM UA solanaUaAddress: smartAccountOptions.solanaSmartAccountAddress!, // SOL UA }; console.log("Smart Account info:", accountInfo); ``` This repository includes a sample Next.js app with social logins via Particle Auth alongside Universal Accounts. ## Fetch Primary Assets Universal Accounts can hold any asset across all supported chains. Among these, **Primary Assets** are the assets that have the deepest liquidity—and, as such, can be used as the base for any cross-chain operation, including **liquidity routing, swaps, and gas payments.** You can find a list of supported Primary Assets in the [Supported chains and Primary Assets](/universal-accounts/cha/chains#primary-assets) page. Primary Assets work independently of the chain on which a user holds them. The SDK will then automatically select the most efficient source and route to execute transactions involving them. For example, if a user wants to buy `$PARTI` via a swap on BNB Chain, the SDK will: * Determine the optimal Primary Asset(s) from the user's portfolio (e.g., USDT on Polygon) to finalize the purchase. * Handle liquidity routing through Universal Liquidity. * Complete the transaction on BNB Chain—even if the user holds **no assets on BNB Chain directly.** You can fetch the **Primary Assets** balance from a Universal Account instance with one call: ```ts theme={null} const primaryAssets = await ua.getPrimaryAssets(); console.log("Primary Assets:", JSON.stringify(primaryAssets, null, 2)); ``` The `getPrimaryAssets()` method will then return a list of **Primary Assets** held by the Universal Account across all supported chains. Each asset includes metadata and a breakdown of holdings per chain. The response returned by `getPrimaryAssets()` has the following structure: ```ts theme={null} { assets: AssetInfo[], totalAmountInUSD: number } ``` You can also retrieve the list of **Primary Assets** supported by Universal Accounts using the `SUPPORTED_PRIMARY_TOKENS` constant from the SDK: ```ts theme={null} import { SUPPORTED_PRIMARY_TOKENS } from "@particle-network/universal-account-sdk"; console.log("Supported Primary Tokens:", SUPPORTED_PRIMARY_TOKENS); ``` This returns an array of token metadata objects, each representing a Primary Asset across supported chains. An example structure would be: ```json JSON [expandable] theme={null} [ { assetId: "eth", type: "eth", chainId: 8453, address: "0x0000000000000000000000000000000000000000", decimals: 18, realDecimals: 18, isMultiChain: true, isMultiChainDefault: true }, ... ] ``` You can then use this object to filter or display supported tokens in your dApp interface, validate token support, or build custom asset selectors based on chain and asset type. ### Asset Structure: `AssetInfo` Each entry in the `assets` array represents a single token type aggregated across chains. | Field | Description | | ------------------ | ------------------------------------------- | | `tokenType` | Token identifier (e.g., "eth", "usdt") | | `price` | Current USD price | | `amount` | Total amount across chains (human-readable) | | `amountInUSD` | Total USD value | | `chainAggregation` | Per-chain balance breakdowns | ### `chainAggregation` format Each `chainAggregation` entry details the balance and metadata of the token on a specific chain: | Field | Description | | --------------------------- | ------------------------------------------------ | | `token.chainId` | Chain ID | | `token.address` | Token contract address | | `amount` | Token amount (human-readable float) | | `amountInUSD` | USD value | | `rawAmount` | Token amount in raw units (integer, stringified) | | `token.decimals` | ERC-20 decimals | | `token.realDecimals` | Adjusted decimals for display | | `token.isMultiChain` | Part of multi-chain registry | | `token.isMultiChainDefault` | Default canonical version across chains | For native assets like `ETH`, the `token.address` field will be `0x0000000000000000000000000000000000000000`. See how to call `getPrimaryAssets()` in a real Next.js app using Particle Auth and Universal Accounts. Check out how Primary Asset data is parsed and rendered in this sample app. ## Sending a Transfer Transaction The `Universal Accounts SDK` lets you send tokens to any address across supported chains using the `createTransferTransaction()` method. Like other transactions, transfers don’t require the user to hold assets or gas tokens on the destination chain—**liquidity and gas are abstracted** behind the scenes. Once you construct the transfer, the SDK returns a `rootHash` to sign. You sign it with the connected EOA (e.g., from Particle Auth), then call `sendTransaction()` to broadcast: ```ts theme={null} import { CHAIN_ID, UniversalAccount } from "@particle-network/universal-account-sdk"; import { useEthereum } from "@particle-network/authkit"; const { provider } = useEthereum(); const transaction = await ua.createTransferTransaction({ token: { chainId: CHAIN_ID.ARBITRUM_MAINNET_ONE, address: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", // USDT on Arbitrum }, amount: "0.1", // Amount to send (human-readable string) receiver: receiverAddress, // Target address }); const signature = await provider.signMessage(transaction.rootHash); const result = await ua.sendTransaction(transaction, signature); console.log("Explorer URL:", `https://universalx.app/activity/details?id=${result.transactionId}`); ``` For native assets like `ETH`, the token address will be `0x0000000000000000000000000000000000000000`. The returned `TransactionResult` will include the transaction ID, as well as metadata like token movements and fee breakdowns. You can find more details about this in the [TransactionResult](/universal-accounts/ua-reference/desktop/web#transactionresult) section below. See how to send cross-chain transfers in a demo Next.js app leveraging Universal Accounts and Particle Auth. ## Sending a Custom Payable Transaction The **Universal Accounts SDK** supports sending contract interactions, including payable transactions, through the `createUniversalTransaction()` method. In this example, we interact with a smart contract on the **Base Mainnet** that requires exactly 0.0000001 ETH to execute a `checkIn()` function. By specifying an `expectTokens` array, the SDK ensures the account has the necessary **ETH** on Base—even if the user’s assets are on other chains or in different tokens (e.g., USDC, USDT). The SDK will handle all additional required cross-chain routing and token conversion under the hood. Once the transaction is created, it will return a `rootHash` value representing the payload to be signed. You can then use a signer (e.g., Particle Auth) to sign this hash and broadcast it using `sendTransaction()`. The following code snippet shows how to use the **Universal Accounts SDK** to send a payable transaction: ```tsx theme={null} import { CHAIN_ID, SUPPORTED_TOKEN_TYPE } from "@particle-network/universal-account-sdk"; import { Interface, parseEther, toBeHex } from "ethers"; import { useEthereum } from "@particle-network/authkit"; // Extract the provider from Particle Auth const { provider } = useEthereum(); const contractAddress = "0x14dcD77D7C9DA51b83c9F0383a995c40432a4578"; const interf = new Interface(["function checkIn() public payable"]); const transaction = await ua.createUniversalTransaction({ chainId: CHAIN_ID.BASE_MAINNET, expectTokens: [ { type: SUPPORTED_TOKEN_TYPE.ETH, amount: "0.0000001", }, ], transactions: [ { to: contractAddress, data: interf.encodeFunctionData("checkIn"), value: toBeHex(parseEther("0.0000001")), }, ], }); const signature = await provider.signMessage(transaction.rootHash); const result = await ua.sendTransaction(transaction, signature); console.log("Explorer URL:", `https://universalx.app/activity/details?id=${result.transactionId}`); ``` The returned `TransactionResult` will include the transaction's ID and metadata like token movements and fee breakdowns. ## Sending a Swap Transaction The Universal Accounts SDK supports initiating **buy/swap transactions** directly through the `createBuyTransaction()` method. This allows you to programmatically route an amount in **USD** into a target token (e.g., USDT on Arbitrum), without requiring the user to hold funds on the destination chain. Once the transaction is created, it returns a `rootHash` value representing the payload to be signed. You then use your **signer** (in this case, Particle Auth) to sign the message, and pass the result into sendTransaction() to broadcast it: ```ts theme={null} import { CHAIN_ID, UniversalAccount } from "@particle-network/universal-account-sdk"; import { useEthereum } from "@particle-network/authkit"; // extract the provider from Particle Auth const { provider } = useEthereum(); // In your app const transaction = await ua.createBuyTransaction({ token: { chainId: CHAIN_ID.ARBITRUM_MAINNET_ONE, address: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", // USDT on Arbitrum }, amountInUSD: "10", // Target amount in USD sourced from primary assets held }); const signature = await provider.signMessage(transaction.rootHash); const result = await ua.sendTransaction(transaction, signature); console.log("Explorer URL:", `https://universalx.app/activity/details?id=${result.transactionId}`); ``` The `sendTransaction` method will then return a `TransactionResult` object, which includes the transaction ID and other metadata. See how to initiate a swap transaction in a demo Next.js app using both Particle Auth and Universal Accounts. ## Sending a Conversion Transaction You can convert between [Primary Assets](/universal-accounts/cha/chains#primary-assets) with the `createConvertTransaction` method. The example below demonstrates how to convert any primary asset into another—USDC on Arbitrum, in this case: ```ts theme={null} import { CHAIN_ID, SUPPORTED_TOKEN_TYPE, UniversalAccount } from "@particle-network/universal-account-sdk"; import { useEthereum } from "@particle-network/authkit"; // extract the provider from Particle Auth const { provider } = useEthereum(); // In your app const transaction = await ua.createConvertTransaction({ expectToken: { type: SUPPORTED_TOKEN_TYPE.USDC, amount: '1' }, chainId: CHAIN_ID.ARBITRUM_MAINNET_ONE, }); const signature = await provider.signMessage(transaction.rootHash); const result = await ua.sendTransaction(transaction, signature); console.log("Explorer URL:", `https://universalx.app/activity/details?id=${result.transactionId}`); ``` This method is useful to convert assets directly to the target chain. ## Solana Transactions Universal Accounts support **Solana** as well. You can swap to and from SOL using the `createTransferTransaction()` method, even if you hold no assets on Solana. Here is an example: ```ts theme={null} import { CHAIN_ID } from "@particle-network/universal-account-sdk"; import { useEthereum } from "@particle-network/authkit"; // extract the provider from Particle Auth const { provider } = useEthereum(); // In your app const transaction = await ua.createBuyTransaction({ // Buy sol // token: { chainId: CHAIN_ID.SOLANA_MAINNET, address: "0x0000000000000000000000000000000000000000" }, // Buy a token token: { chainId: CHAIN_ID.SOLANA_MAINNET, address: "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN" }, // buy $0.001 of trump amountInUSD: "0.001", }); const signature = await provider.signMessage(transaction.rootHash); const result = await universalAccount.sendTransaction(transaction, signature); console.log("Explorer URL:", `https://universalx.app/activity/details?id=${result.transactionId}`); ``` Even if your Universal Account doesn’t hold SOL for gas, you can still purchase SOL or any other Solana token. Universal Accounts will automatically handle routing and liquidity across chains to cover gas fees. Solana transactions can be signed with any provider compatible with the Universal Accounts SDK. In this case, Particle Auth is used to sign the `rootHash`. You can combine this swap transaction with a SOL transfer to automatically convert EVM-based assets to SOL and send them to another account in a single flow. ## Transaction Preview The transaction object returned by methods like `createTransferTransaction()` provides a full preview of the transaction before it’s executed. This includes key details such as estimated fees, token transfers, and other relevant metadata—allowing you to display clear, actionable information to users before confirmation. For example: ```tsx page.tsx theme={null} const transaction = await universalAccount.createBuyTransaction({ token: { chainId: CHAIN_ID.BSC_MAINNET, address: "0x59264f02D301281f3393e1385c0aEFd446Eb0F00", // PARTI token on BNB Chain }, amountInUSD: "1", }); ``` The returned transaction object includes **metadata** such as **sender** and **recipient** addresses, **tokens** used, and **estimated fees**. Here’s how to extract and display the estimated fees: ```ts page.tsx theme={null} import { formatUnits } from "ethers"; const feeQuote = transaction.feeQuotes[0]; const fee = feeQuote.fees.totals; console.log("Total fee (USD):", `$${formatUnits(fee.feeTokenAmountInUSD, 18)}`); console.log("Gas fee (USD):", `$${formatUnits(fee.gasFeeTokenAmountInUSD, 18)}`); console.log("Service fee (USD):", `$${formatUnits(fee.transactionServiceFeeTokenAmountInUSD, 18)}`); console.log("LP fee (USD):", `$${formatUnits(fee.transactionLPFeeTokenAmountInUSD, 18)}`); ``` For a full breakdown of the preview structure and practical usage examples, see the [Preview Transaction Details with Universal Accounts](/universal-accounts/cha/how-to/tx-preview) guide. ## `sendTransaction()` Response Structure After broadcasting a transaction with `sendTransaction()`, the SDK will return a detailed object containing its execution status, fee breakdowns, token flows, and analytics. Below is a breakdown of the key fields within this object: | Field | Description | | --------------------------- | ----------------------------------------------------------------------- | | `transactionId` | Unique ID of the transaction (used to query status or activity details) | | `mode` | Network mode, typically `"mainnet"` or `"testnet"` | | `sender` / `receiver` | Address that initiated and received the transaction (usually same) | | `type` | Transaction type (e.g. `"universal"`) | | `status` | Execution status code (internal enum) | | `tag` | Transaction tag (e.g., `"buy"` or `"swap"`) | | `created_at` / `updated_at` | ISO timestamps for lifecycle tracking | | Field | Description | | ------------------------------- | ------------------------------------------------------------ | | `totals.feeTokenAmountInUSD` | Total fee in USD | | `feeTokens[]` | List of tokens used to pay fees, with symbols and USD values | | `freeGasFee` / `freeServiceFee` | Whether any component was waived | Tokens deducted from the user's account to fund the transaction. Each entry includes: * `token.symbol` * `token.chainId` * `amount` and `amountInUSD` * Full metadata (decimals, icon, etc.) Provides the most useful high-level insight into what changed: | Field | Description | | ----------------- | ---------------------------------------------------- | | `decr[]` | Tokens deducted from the user (chain, token, amount) | | `incr[]` | Tokens received by the user | | `swaps[]` | Swap routes (e.g. from USDC to USDT via 1inch) | | `tokenBalances[]` | Final post-transaction token balances | | Field | Description | | ----------------------- | -------------------------------------------------------------- | | `slippage` | Slippage used for the route (in basis points) | | `totalFeeInUSD` | Final USD fee value | | `totalDecrAmountInUSD` | Total USD value deducted | | `totalIncrAmountInUSD` | Total USD value received | | `priceImpact` | Estimated price impact (0 if none) | | `minReceiveAmountInUSD` | Minimum expected amount (to be received, post-slippage) in USD | | `minReceiveToken` | Token targeted by the buy/swap action | You can construct a link to see the activity on UniversalX: ```ts theme={null} const url = `https://universalx.app/activity/details?id=${transactionId}`; ``` ## Using Particle Connect with Universal Accounts The following example uses **Particle Connect** instead of Particle Auth. It shows how to sign and send a Universal Account transaction using a connected wallet. When using **Particle Connect**, you can access the connected wallet through the `useWallets()` hook. The `primaryWallet` object exposes a `walletClient`, which acts as the signer. This lets you sign the **Universal Account transaction** payload (rootHash) using any **wallet** connected via **Particle Connect**. The following code snippet shows how to use the **Universal Accounts SDK** to sign a transaction with Particle Connect: ```tsx theme={null} import { useWallets, useAccount } from "@particle-network/connectkit"; import { CHAIN_ID } from "@particle-network/universal-account-sdk"; // Get wallet from Particle Connect const [primaryWallet] = useWallets(); const walletClient = primaryWallet?.getWalletClient(); const { address } = useAccount(); // Create a cross-chain transfer transaction via Universal Accounts const transaction = await universalAccount.createTransferTransaction({ token: { chainId: CHAIN_ID.ARBITRUM_MAINNET_ONE, address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum }, amount: "0.1", receiver: "0x5ca4d471dC47F23B75C40cB4Dd5D8dc4618A3bD5", rpcUrl: "https://arb1.arbitrum.io/rpc", }); // Sign the transaction's root hash using connected wallet const signature = await walletClient?.signMessage({ account: address as `0x${string}`, message: { raw: transaction.rootHash }, }); // Send the signed transaction via Universal Account SDK const sendResult = await universalAccount.sendTransaction( transaction, signature ); // Log UniversalX explorer link console.log( "Explorer URL:", `https://universalx.app/activity/details?id=${sendResult.transactionId}` ); ``` ## Using Universal Accounts in the backend The **Universal Accounts SDK** can also be used in backend environments to construct and sign transactions programmatically. The example below demonstrates usage with ethers.js and a private key in Node.js: ```ts theme={null} import { UniversalAccount, CHAIN_ID } from "@particle-network/universal-account-sdk"; import { Wallet, getBytes } from "ethers"; // Initialize wallet const wallet = new Wallet("PRIVATE_KEY_OR_MNEMONIC"); // Create a Universal Account instance const ua = new UniversalAccount({ projectId: "UA_PROJECT_ID", ownerAddress: wallet.address, tradeConfig: { slippageBps: 100, // Set slippage to 1% (100 basis points) universalGas: true // Use PARTI tokens to cover gas fees } }); // Create a transaction to buy $0.1 worth of ARB on Arbitrum const tx = await ua.createBuyTransaction({ token: { chainId: CHAIN_ID.ARBITRUM_MAINNET_ONE, address: "0x912CE59144191C1204E64559FE8253a0e49E6548" // ARB token contract }, amountInUSD: "0.1" }); // Sign and send the transaction const result = await ua.sendTransaction(tx, wallet.signMessageSync(getBytes(tx.rootHash))); // Log the transaction result and link to explorer console.log("Transaction ID:", result.transactionId); console.log("View on Explorer:", `https://universalx.app/activity/details?id=${result.transactionId}`); ``` ## Registering a UniversalX Account The **Universal Accounts SDK** also allows you to register an account on [UniversalX](https://universalx.app), a chain-abstracted trading platform built upon **Universal Accounts**. This can automatically onboard your users into **UniversalX** when they create or initialize a Universal Account. UniversalX registration is optional and only needs to be done **once per UA**. ```ts theme={null} import { UniversalAccount, createUnsignedMessage } from "@particle-network/universal-account-sdk"; import { randomUUID } from "crypto"; const ua = new UniversalAccount({ projectId: process.env.PROJECT_ID || "", ownerAddress: 'USER_ADDRESS', }); // Fetch smart account info to get the UA address const smartAccountOptions = await ua.getSmartAccountOptions(); // Optional invite code const inviteCode = "000000"; // Prepare registration payload const deviceId = randomUUID(); const timestamp = Date.now(); const unsignedMessage = createUnsignedMessage( smartAccountOptions.smartAccountAddress!, deviceId, timestamp ); // Sign message using EOA (can be a backend wallet) const signature = provider.signMessage(unsignedMessage); // Register the UniversalX account const result = await ua.register(inviteCode, deviceId, timestamp, signature); if (!!result.token) { console.log("Registration successful."); } else { console.error("Registration failed:", result); } ``` You can also pass an invite code (`"000000"` by default) if you have one.