Learn More About Universal Accounts
What are Universal Accounts, how do they work, and what problems do they solve?
The following examples use a React-based app alongside Particle Auth for authentication and wallet connection.However, the Universal Accounts SDK is provider-agnostic—alongside it, you can also use Particle Connect, Web3Modal, RainbowKit, or any signer.You can also use the SDK to construct and sign transactions programmatically on the server side.
1
Connect a user's account
A user logs into their account by connecting a wallet or via a social login.
2
Initialize Universal Accounts
Once connected, pass the user’s EOA address to the SDK and configure your project’s details.
3
Use the UA instance
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.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.Import and Configure
You can access and import theUniversalAccount
class in your app from @particle-network/universal-account-sdk
:
The Universal Account SDK requires Particle project credentials from the Particle Dashboard.
Access the Particle Dashboard
Access the Particle Dashboard
Sign up or Log in into the Particle dashboard

Create a new project or enter an existing project
Create a new project or enter an existing project

Create a new web application, or skip this step if you already have one
Create a new web application, or skip this step if you already have one

Retrieve the project credentials (project ID, client key, app ID)
Retrieve the project credentials (project ID, client key, app ID)

ua
instance to fetch data (a Universal Account’s balance or addresses) and send transactions.
Check Out UA Initialization in this Sample Repository
Repository of sample Next.js app with social logins via Particle Auth + UA.
Control which tokens are used for swaps
When initializing a Universal Account, you can control which tokens are eligible to be used as the source for swap operations. To do this, set theusePrimaryTokens
field inside the tradeConfig
object. This lets you restrict swap logic to specific tokens (e.g. only allow SOL to be spent, not USDT or ETH).
Example:
- Ensure predictable token usage during swaps
- Prevent certain tokens from being auto-selected as swap input
- Customize the user experience around token prioritization
Get a Universal Account’s Addresses
A Universal Account is composed of multiple addresses, each relevant to a specific interaction layer:- Owner Address: The EOA that owns the Universal Account and signs transactions (e.g., from MetaMask or via a social login).
- EVM Universal Address: The UA address used on EVM-compatible chains.
- 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.
UA Info Management
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 page.
$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.
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.
getPrimaryAssets()
has the following structure:
SUPPORTED_PRIMARY_TOKENS
constant from the SDK:
JSON
Asset Structure: AssetInfo
Each entry in the assets
array represents a single token type aggregated across chains.
Expand to see the full structure
Expand to see the full structure
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:
Expand to see the full structure
Expand to see the full structure
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
.Fetch Primary Assets in a Sample App
See how to call
getPrimaryAssets()
in a real Next.js app using Particle Auth and Universal Accounts.Parse and Display Asset Balances
Check out how Primary Asset data is parsed and rendered in this sample app.
Sending a Transfer Transaction
TheUniversal 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:
For native assets like
ETH
, the token address will be 0x0000000000000000000000000000000000000000
.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 section below.
View a Sample Transfer Transaction
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 thecreateUniversalTransaction()
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:
TransactionResult
will include the transaction’s ID and metadata like token movements and fee breakdowns.
Sending a Buy Transaction
The Universal Accounts SDK supports initiating buy/swap transactions directly through thecreateBuyTransaction()
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:
You can specify the specific tokens you want to use as source for the swap by setting the
usePrimaryTokens
property in the tradeConfig
object when initializing the Universal Account.sendTransaction
method will then return a TransactionResult
object, which includes the transaction ID and other metadata.
Sample Swap Transaction
See how to initiate a swap transaction in a demo Next.js app using both Particle Auth and Universal Accounts.
Sending a Sell Transaction
The Universal Accounts SDK supports initiating sell/swap transactions through thecreateSellTransaction()
method. This allows you to programmatically sell a token (e.g., ARB on Arbitrum) into a target primary asset, with the transaction routed through Particle’s Chain Abstraction layer.
Once the transaction is created, it returns a rootHash
payload that needs to be signed. You then use your signer (e.g., Particle Auth) to sign and pass it into sendTransaction()
to broadcast.
The amount you specify is the raw token amount to be sold (no decimals adjustment needed). Ensure the Universal Account has enough balance of the token before calling
createSellTransaction()
.sendTransaction(
) method returns a TransactionResult
object with the transaction ID and other metadata.
Sending a Conversion Transaction
You can convert between Primary Assets with thecreateConvertTransaction
method.
The example below demonstrates how to convert any primary asset into another—USDC on Arbitrum, in this case:
Solana Transactions
Universal Accounts support Solana as well. You can swap to and from SOL using thecreateTransferTransaction()
method, even if you hold no assets on Solana.
Here is an example:
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.
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 likecreateTransferTransaction()
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:
page.tsx
page.tsx
For a full breakdown of the preview structure and practical usage examples, see the Preview Transaction Details with Universal Accounts 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:
Top-Level Fields
Top-Level Fields
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 |
`fees` (Cost Breakdown)
`fees` (Cost Breakdown)
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 |
`depositTokens` / `lendingTokens`
`depositTokens` / `lendingTokens`
Tokens deducted from the user’s account to fund the transaction. Each entry includes:
token.symbol
token.chainId
amount
andamountInUSD
- Full metadata (decimals, icon, etc.)
tokenChanges (Before/After Effects)
tokenChanges (Before/After Effects)
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 |
Analytics & Valuation
Analytics & Valuation
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 |
`Explorer / Activity Link`
`Explorer / Activity Link`
You can construct a link to see the activity on UniversalX:
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.
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:
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:Registering a UniversalX Account
The Universal Accounts SDK also allows you to register an account on UniversalX, 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.You can also pass an invite code (
"000000"
by default) if you have one.