API Reference

Constructor

Creates a new MythicalProvider instance.

new MythicalProvider(hostOrigin: string)

Parameters

Parameter	Type	Description
hostOrigin	string	The origin of the Mythical Store host window

Example

// Production
const provider = new MythicalProvider("https://store.mythicalbeings.io");

// Testnet
const provider = new MythicalProvider("https://testnet.mythicalbeings.io");

connect()

Requests a connection to the wallet with specified permissions.

connect(options: ConnectOptions): Promise<Session>

Parameters

Option	Type	Required	Description
appName	string	Yes	Your application's display name
appIconUrl	string	No	URL to your app's icon (shown in modal)
permissions	Permission[]	Yes	Array of permissions to request

Returns

interface Session {
  accountRS: string;    // "ARDOR-XXXX-XXXX-XXXX-XXXXX"
  publicKey: string;    // Hex-encoded public key
  permissions: Permission[];
}

Example

const session = await provider.connect({
  appName: "My Game",
  appIconUrl: "https://example.com/icon.png",
  permissions: ["READ_ACCOUNT", "READ_BALANCES", "TX_SEND_IGNIS"]
});

console.log(session.accountRS);  // "ARDOR-..."
console.log(session.permissions); // ["READ_ACCOUNT", ...]

disconnect()

Disconnects from the wallet and clears the session.

disconnect(): Promise<void>

Example

await provider.disconnect();
console.log("Disconnected");

getSession()

Returns the current session, or null if not connected.

getSession(): Promise<Session | null>

Example

const session = await provider.getSession();
if (session) {
  console.log("Connected as:", session.accountRS);
} else {
  console.log("Not connected");
}

getBalances()

Gets the user's IGNIS and asset balances.

getBalances(): Promise<Balances>

Returns

interface Balances {
  ignisNQT: string;           // IGNIS balance in NQT
  unconfirmedIgnisNQT: string;
  assets: AssetBalance[];
}

interface AssetBalance {
  asset: string;        // Asset ID
  name: string;         // Asset name
  quantityQNT: string;  // Quantity in QNT
  decimals: number;     // Asset decimals (0-8)
}

Example

import { formatNQTToIgnis } from "@mythicalb/ardor-core";

const balances = await provider.getBalances();

// IGNIS balance
const ignis = formatNQTToIgnis(balances.ignisNQT);
console.log(`IGNIS: ${ignis}`);

// Assets
for (const asset of balances.assets) {
  console.log(`${asset.name}: ${asset.quantityQNT}`);
}

getAssets()

Gets detailed information about the user's assets.

getAssets(): Promise<AssetInfo[]>

sendIgnis()

Sends IGNIS to another account. Requires user approval.

sendIgnis(options: SendIgnisOptions): Promise<TransactionResult>

Parameters

Option	Type	Required	Description
recipientRS	string	Yes	Recipient's Ardor address
amount	{ ignis: string } | { nqt: string }	Yes	Amount to send
message	string	No	Plain text message

Returns

interface TransactionResult {
  fullHash: string;           // Transaction hash
  transactionId: string;      // Transaction ID
  broadcasted: boolean;
}

Example

// Send 10.5 IGNIS
const result = await provider.sendIgnis({
  recipientRS: "ARDOR-XXXX-XXXX-XXXX-XXXXX",
  amount: { ignis: "10.5" },
  message: "Payment for item"
});

console.log("TX Hash:", result.fullHash);

transferAsset()

Transfers an asset to another account. Requires user approval.

transferAsset(options: TransferAssetOptions): Promise<TransactionResult>

Parameters

Option	Type	Required	Description
recipientRS	string	Yes	Recipient's Ardor address
assetId	string	Yes	Asset ID to transfer
quantityQNT	string	Yes	Quantity in QNT (smallest unit)

Example

const result = await provider.transferAsset({
  recipientRS: "ARDOR-XXXX-XXXX-XXXX-XXXXX",
  assetId: "123456789012345678",
  quantityQNT: "1"  // 1 unit
});

console.log("Asset transferred:", result.fullHash);

sendMessage()

Sends a plain text message on the blockchain.

sendMessage(options: SendMessageOptions): Promise<TransactionResult>

sendEncryptedMessage()

Sends an encrypted message that only the recipient can read.

sendEncryptedMessage(options: SendEncryptedMessageOptions): Promise<TransactionResult>

Parameters

Option	Type	Required	Description
recipientRS	string	Yes	Recipient's Ardor address
message	string	Yes	Message content
recipientPublicKey	string	No	Required if recipient has never sent a TX

placeAskOrder()

Places a sell order on the marketplace.

placeAskOrder(options: PlaceOrderOptions): Promise<TransactionResult>

Parameters

Option	Type	Description
assetId	string	Asset ID to sell
quantityQNT	string	Quantity to sell
priceNQTPerShare	string	Price in NQT per share

Example

// Sell 1 unit for 10 IGNIS
const result = await provider.placeAskOrder({
  assetId: "123456789012345678",
  quantityQNT: "1",
  priceNQTPerShare: "1000000000" // 10 IGNIS
});

placeBidOrder()

Places a buy order on the marketplace.

placeBidOrder(options: PlaceOrderOptions): Promise<TransactionResult>

cancelAskOrder()

Cancels an existing sell order.

cancelAskOrder(options: { orderId: string }): Promise<TransactionResult>

cancelBidOrder()

Cancels an existing buy order.

cancelBidOrder(options: { orderId: string }): Promise<TransactionResult>

signToken()

Signs an authentication token to prove account ownership.

signToken(): Promise<SignedToken>

Returns

interface SignedToken {
  token: string;      // The signed token
  signature: string;  // Cryptographic signature
  accountRS: string;  // Signer's account
  timestamp: number;  // When it was signed
}

Example

const { token, signature, accountRS } = await provider.signToken();

// Send to your backend for verification
await fetch('/api/verify', {
  method: 'POST',
  body: JSON.stringify({ token, signature, accountRS })
});

on()

Subscribes to wallet events.

on(event: EventType, callback: (data: EventData) => void): void

Events

Event	Data	Description
accountChanged	{ accountRS, publicKey }	User switched accounts
locked	{}	Wallet was locked
unlocked	{}	Wallet was unlocked
networkChanged	{ isTestnet }	Network configuration changed
sessionChanged	{ permissions }	Session permissions updated

Example

provider.on("accountChanged", (event) => {
  console.log("Account changed to:", event.accountRS);
  refreshUserData();
});

provider.on("locked", () => {
  showLoginPrompt();
});

off()

Unsubscribes from wallet events.

off(event: EventType, callback?: Function): void

Amount Conversion Functions

Utility functions from @mythicalb/ardor-core for converting between human-readable amounts and blockchain units.

import {
  parseIgnisToNQT,      // "10.5" → 1050000000n
  formatNQTToIgnis,     // 1050000000n → "10.5"
  parseDecimalToQNT,    // ("1.5", 4) → 15000n
  formatQNTToDecimal,   // (15000n, 4) → "1.5"
  formatFeeDisplay,     // 10000000n → "0.1 IGNIS"
  formatFeeForModal,    // (10000000n, "Fee") → "Fee: 0.1 IGNIS"
  getFeeBreakdown       // Returns { nqt, ignis, display, label }
} from "@mythicalb/ardor-core";

Example

// IGNIS conversions (8 decimals)
const nqt = parseIgnisToNQT("10.5");
// → 1050000000n

const ignis = formatNQTToIgnis(1050000000n);
// → "10.5"

// Asset conversions (variable decimals)
const qnt = parseDecimalToQNT("1.5", 4);
// → 15000n

const decimal = formatQNTToDecimal(15000n, 4);
// → "1.5"

// Fee display
const fee = formatFeeDisplay(10000000n);
// → "0.1 IGNIS"

Error Codes

Standard error codes thrown by the SDK:

Code	Name	Description
4001	USER_REJECTED	User rejected the request
4100	UNAUTHORIZED_ORIGIN	Request from unauthorized origin
4101	NOT_CONNECTED	Not connected to wallet
4102	PERMISSION_DENIED	Missing required permission
4200	WALLET_LOCKED	Wallet is locked
4201	NO_ACTIVE_ACCOUNT	No account selected
4300	INVALID_PARAMS	Invalid parameters
4301	ARDOR_NODE_ERROR	Error from Ardor node
4302	TX_BUILD_FAILED	Failed to build transaction
4303	TX_SIGN_FAILED	Failed to sign transaction
4304	TX_BROADCAST_FAILED	Failed to broadcast transaction
5000	INTERNAL_ERROR	Internal SDK error

import { MythicalError, MythicalErrorCode } from "@mythicalb/ardor-core";

try {
  await provider.sendIgnis({ ... });
} catch (error) {
  if (error instanceof MythicalError) {
    console.log("Code:", error.code);
    console.log("Message:", error.message);
    console.log("Data:", error.data);
  }
}