Quick Start

Installation

Install the SDK using npm:

# Install the provider (for your game)
npm install @mythicalb/ardor-provider

# Core utilities are included as dependency, but can be installed separately
npm install @mythicalb/ardor-core

Basic Setup

Import the provider and create an instance. Your game must be running inside an iframe on the Mythical Beings store.

import { MythicalProvider } from "@mythicalb/ardor-provider";

// Create provider with the store's origin
const provider = new MythicalProvider("https://store.mythicalbeings.io");

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

Connect to Wallet

Request a connection with the permissions your game needs:

async function connectWallet() {
  try {
    const session = await provider.connect({
      appName: "My Awesome Game",
      appIconUrl: "https://mygame.com/icon.png",
      permissions: [
        "READ_ACCOUNT",      // Read account address
        "READ_BALANCES",     // Read IGNIS and asset balances
        "TX_SEND_IGNIS",     // Send IGNIS payments
        "TX_TRANSFER_ASSET"  // Transfer game assets
      ]
    });

    console.log("Connected to:", session.accountRS);
    console.log("Public key:", session.publicKey);
    
    return session;
  } catch (error) {
    if (error.code === 4001) {
      console.log("User rejected the connection");
    } else {
      console.error("Connection failed:", error);
    }
  }
}

When you call connect(), the user sees a permission modal:

Read Balances

Once connected, you can read the user's balances:

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

// Get all balances
const balances = await provider.getBalances();

// IGNIS balance (in NQT - 8 decimals)
console.log("Raw balance:", balances.ignisNQT);
// → "1050000000"

// Convert to human-readable
const ignis = formatNQTToIgnis(balances.ignisNQT);
console.log("IGNIS:", ignis);
// → "10.5"

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

Send a Transaction

All transactions require user approval. The user sees a confirmation modal with transaction details.

// Send IGNIS to another player
try {
  const result = await provider.sendIgnis({
    recipientRS: "ARDOR-XXXX-XXXX-XXXX-XXXXX",
    amount: { ignis: "5.0" },
    message: "Thanks for the trade!"
  });

  console.log("Transaction sent!");
  console.log("TX ID:", result.fullHash);
} catch (error) {
  if (error.code === 4001) {
    console.log("User rejected the transaction");
  } else {
    console.error("Transaction failed:", error);
  }
}

Handle Events

Listen for wallet events to keep your game in sync:

// Account changed (user switched accounts)
provider.on("accountChanged", (event) => {
  console.log("New account:", event.accountRS);
  // Reload user data
  refreshGameState();
});

// Wallet locked
provider.on("locked", () => {
  console.log("Wallet locked");
  showLoginPrompt();
});

// Wallet unlocked
provider.on("unlocked", () => {
  console.log("Wallet unlocked");
  hideLoginPrompt();
});

// Session changed (permissions updated)
provider.on("sessionChanged", (event) => {
  console.log("Session updated:", event.permissions);
});

// Network changed
provider.on("networkChanged", (event) => {
  console.log("Network:", event.isTestnet ? "Testnet" : "Mainnet");
});

Permissions

Request only the permissions your game actually needs:

Permission	Description
READ_ACCOUNT	Read the user's account address
READ_BALANCES	Read IGNIS and asset balances
TX_SEND_IGNIS	Send IGNIS payments (requires approval)
TX_TRANSFER_ASSET	Transfer assets (requires approval)
TX_SEND_MESSAGE	Send plain or encrypted messages
TX_MARKETPLACE	Place/cancel marketplace orders
SIGN_TOKEN	Sign authentication tokens

Error Handling

The SDK uses standardized error codes:

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

try {
  await provider.sendIgnis({ ... });
} catch (error) {
  switch (error.code) {
    case MythicalErrorCode.USER_REJECTED: // 4001
      console.log("User rejected");
      break;
    case MythicalErrorCode.WALLET_LOCKED: // 4200
      console.log("Wallet is locked");
      break;
    case MythicalErrorCode.PERMISSION_DENIED: // 4102
      console.log("Missing permission");
      break;
    case MythicalErrorCode.TX_BROADCAST_FAILED: // 4304
      console.log("Transaction failed:", error.message);
      break;
    default:
      console.error("Unknown error:", error);
  }
}

See the Error Codes guide for a complete list.

Production Checklist

Before going live, make sure you:

• ✅ Use the production origin: https://store.mythicalbeings.io
• ✅ Request only the permissions you need
• ✅ Handle all error cases gracefully
• ✅ Show loading states during transactions
• ✅ Listen for accountChanged and locked events
• ✅ Test on both mainnet and testnet
• ✅ Check browser compatibility (Chrome 92+, Firefox 95+, Safari 15.4+)