Core API Methods
The @ultraos/wallet-sdk
provides a unified interface for interacting with both the Ultra Web Wallet and the Ultra Wallet Extension. This means you can implement wallet functionality once, and the SDK will handle which wallet environment (web or extension) is used behind the scenes.
Response Format
The Ultra Web Wallet SDK returns responses in the same format as the Ultra Wallet Extension.
Each successful method call returns a consistent object structure with the following top-level fields:
status
: Always"success"
for resolved callsdata
: The actual payload of the response, specific to each method
Example structure:
{
status: "success",
data: {
// method-specific values here
}
}
For full details on the structure of each method’s response, refer to the shared documentation:
See Ultra Wallet Response Format →
Connect
Initiates the connection process with the wallet. For Web Wallet users, this includes authenticating via Ultra SSO and registering the device.
try {
const response = await wallet.connect();
response.data.blockchainid;
// ej1vx2ft3ht4
response.data.publicKey;
// EOS7uRb72dR8jrLjNuC9UoevBBH3YbVZfNKUtYCfLkV7aPGcmDjs7
} catch (err) {
// { status: "error", message: "Connection rejected" }
}
Eagerly Connecting
After a web application connects to the Ultra Wallet for the first time, it gains a trusted status. Once this trust is established, the application can seamlessly link with Ultra Wallet during future visits or when the page is refreshed, eliminating the need to ask the user for authorization. This concept is commonly known as "eagerly connecting".
To implement this, web applications should pass an onlyIfTrusted
option into the connect()
call.
try {
await wallet.connect({ onlyIfTrusted: true });
} catch (err) {
// { status: 'error', code: 4001, message: 'The user rejected the request.' }
}
Sending a Referral Code
An application can send its referral code to the wallet. The referral code will be used if the user signs up during the connection process.
To implement this, applications should pass the referralCode
option into the connect()
call.
wallet.connect({ referralCode: 'ecd1f052-9d0d-4b84-8dd3-10a753d044b5' });
To get your referral code, go to the Ultra Desktop client and then to the Wallet, and look for the "My referral link" section. Click the link to copy it.
Once you copy your referral link, you can extract the referral code from the URL. For example, from the following link:
https://ultra.io/register/ecd1f052-9d0d-4b84-8dd3-10a753d044b5
The referral code is: ecd1f052-9d0d-4b84-8dd3-10a753d044b5
.
Connect with Nonce
To streamline authentication flows and avoid browser restrictions on multiple popup windows, the connect()
method supports an optional nonce
parameter. When provided, the Ultra Web Wallet will automatically sign the nonce after completing key synchronization.
This is particularly useful for dApps that need to verify user identity using a signed challenge (i.e., the nonce) — commonly used in Web3 login/session flows.
Note
If the nonce
parameter is specified, the connect()
method will always prompt the user to reconnect, even if a trusted session already exists.
Usage
try {
const response = await wallet.connect({ nonce: 'abc123randomnonce' });
console.log(response.data.blockchainid); // e.g., "aa1aa2aa3aa4"
console.log(response.data.publicKey); // e.g., "EOS7HUZZ6AQvrEi3wGRrKd2A3CuktaeM6xnguA2CrVxH9BUMB5aRx"
console.log(response.data.nonce); // "message: abc123randomnonce" (note: nonce must start with 'message:', '0x', or 'UOSx')
console.log(response.data.signedNonce); // Signed message
} catch (err) {
// { status: "error", message: "Connection rejected" }
}
Important: The
nonce
string must begin with one of the supported prefixes:'message:'
,'0x'
, or'UOSx'
. This ensures compatibility with Ultra Wallet’s signature rules.
Response Format
When a nonce
is provided, the response data
object will include:
blockchainid
: User's Ultra Blockchain IDpublicKey
: Associated public keynonce
: The original nonce sent by the dAppsignedNonce
: The message signature generated by the Ultra Wallet
This signed payload can then be verified off-chain or used to create stateless sessions server-side.
Note: The signed message uses the standard
signMessage()
behavior with the same signature rules.
Disconnect
The disconnect()
method revokes the connection permission that the user granted to the web application. If the application is already disconnected, the Promise will throw an error.
try {
await wallet.disconnect();
} catch (err) {
// { status: "error", message: "Forbidden" }
Sign Message
In some cases, a web application can also request the user to sign a given message to verify the ownership of a blockchain account. Applications are free to write their messages which will be displayed to users from within the Ultra Wallet's signature prompt using the method signMessage()
. These messages should have one of the following prefixes: 0x
, UOSx
, or message:
.
const signature = await wallet.signMessage('message: Hello, blockchain!');
INFO
Message signatures do not involve network fees.
Sign Transaction
Once a web application is connected to the Ultra Wallet, it can prompt the user for permission to sign and push transactions on their behalf.
Create a transaction object
Ultra Wallet uses a simplified format for transaction objects. The required fields are action
, contract
, and data
.
Example: sending tokens between accounts.
{
"action": "transfer",
"contract": "eosio.token",
"data": {
"memo": "This is a transaction test",
"quantity": "11.20000000 UOS",
"from": "ej1vx2ft3ht4",
"to": "nwyklp2aa1qd"
}
}
Sign the transaction object
Once the transaction is created, you can request the wallet to sign and broadcast it using signTransaction()
:
try {
const response = await wallet.signTransaction(txObject);
response.data.transactionHash;
// 51c6d324522a0ee05baeee2a8857b016e47481207850074ee83f914e6adc45ae
} catch (err) {
// { status: "error", message: "Transaction declined" }
}
Sign multiple transactions at the same time
You can also pass an array of transactions to sign them together in a single call:
const txArray = [
{
action: 'transfer',
contract: 'eosio.token',
data: {
memo: '',
quantity: '11.20000000 UOS',
from: 'ej1vx2ft3ht4',
to: 'nwyklp2aa1qd',
},
},
{
action: 'buy',
contract: 'eosio.nft.ft',
data: {
buy: {
token_id: 9974,
buyer: 'mg1vg2lv3fs4',
receiver: 'mg1vg2lv3fs4',
max_price: '78.00000000 UOS',
memo: '',
promoter_id: null,
},
},
},
];
try {
const response = await wallet.signTransaction(txArray);
response.data.transactionHash;
} catch (err) {
// { status: "error", message: "Transaction declined" }
}
Sign a transaction without broadcasting to the blockchain
You can sign one or more transactions and receive the full signed payload without broadcasting it by passing { signOnly: true }
:
try {
const response = await wallet.signTransaction(txObject, { signOnly: true });
response.data;
/**
{
"expiration": "...",
"ref_block_num": ...,
"actions": [...],
"signatures": [...],
...
}
*/
} catch (err) {
// { status: "error", message: "Transaction declined" }
}
Get Chain ID
Retrieves the current chain ID based on the environment configuration.
const chainId = await wallet.getChainId();
Purchase Item
To facilitate the purchase of a Uniq Factory with FIAT or blockchain tokens, the Ultra platform provides the wallet.purchaseItem(itemType, itemId)
method. This method initiates a complete purchase flow for a specific item, identified by its type and ID on the blockchain.
Parameters
itemType
: For Uniq Factory purchases, use"UniqFactory"
.itemId
: The numeric identifier of the Uniq Factory product on the blockchain.
When this method is called, a popup will appear showing the Ultra purchase flow. Users can complete their purchase using credit/debit cards or UOS tokens.
Upon success, the result includes:
orderHash
: Reference ID for customer supportitems
: An array of purchased items containing:productId
: The requested item IDartifactId
: The minted Uniq on the blockchainblockchainTransactionId
: Transaction ID confirming the mint on-chain
If the user cancels or an error occurs, the promise will reject with an error message.
try {
const response = await wallet.purchaseItem('UniqFactory', '599');
// {
// status: "success",
// data: {
// orderHash: "XXX",
// items: [{
// productId: 599,
// artifactId: 7777,
// blockchainTransactionId: "XXX",
// }],
// },
// }
} catch (err) {
// { status: "error", message: "Purchase canceled" }
}
Error Codes
The Ultra Web Wallet SDK follows the same error interface as the Ultra Wallet Extension.
When a method fails (e.g., the user cancels a transaction or rejects a connection request), the rejected promise will contain a standardized error object with fields like status
, code
, and message
.
You can refer to the shared error documentation for full details on all possible error responses: