FHEx Wallet SDK

TypeScript SDK for websites that connect to the FHEx Chrome extension on Octra.

The extension injects a browser provider at window.octra. This package wraps that provider with a stable dApp API, typed transactions, amount helpers, provider detection, and direct browser-script support.

Install

npm install fhex-octra-sdk

For a direct browser script:

<script src="https://unpkg.com/fhex-octra-sdk/dist/fhex-wallet-sdk.js"></script>

That exposes window.FhexWallet and window.FhexWalletSDK.

Quick Start

import { fhex, octToBaseUnits } from "fhex-octra-sdk";

const { address } = await fhex.connect({
  permissions: ["read_address", "send_transactions"]
});

const result = await fhex.sendTransaction({
  from: address,
  to_: "oct...",
  amount: octToBaseUnits("1.25"),
  ou: "1000",
  op_type: "standard",
  message: "hello"
});

console.log(result);

Vanilla Browser Example

<button id="connect">Connect FHEx</button>
<button id="send">Send 1 OCT</button>
<script src="./dist/fhex-wallet-sdk.js"></script>
<script>
  let currentAddress = "";

  document.getElementById("connect").onclick = async () => {
    const { address } = await FhexWallet.connect();
    currentAddress = address;
    console.log("Connected", address);
  };

  document.getElementById("send").onclick = async () => {
    const tx = {
      from: currentAddress,
      to_: "oct...",
      amount: FhexWalletSDK.octToBaseUnits("1"),
      ou: "1000",
      op_type: "standard"
    };
    console.log(await FhexWallet.sendTransaction(tx));
  };
</script>

Provider Detection

import { isInstalled, waitForProvider } from "fhex-octra-sdk";

if (!isInstalled()) {
  console.log("Ask the user to install FHEx Wallet");
}

await waitForProvider({ timeoutMs: 12000 });

The extension dispatches octra#initialized when the provider is injected.

API

const { address, accounts } = await fhex.connect();
const allAccounts = await fhex.accounts();
const activeAddress = await fhex.address();
const balance = await fhex.getBalance();
const chainId = await fhex.getChainId();
const network = await fhex.getNetwork();
const networkId = await fhex.getNetworkId();
const networkInfo = await fhex.getNetworkInfo();
const permissions = await fhex.permissions();

Signing and transactions:

const signedMessage = await fhex.signMessage({ message: "Login to my dApp" });
const fee = await fhex.estimateFee(tx);
const signedTx = await fhex.signTransaction(tx);
const submitted = await fhex.sendTransaction(tx);

Raw provider access:

const result = await fhex.request("octra_accounts", []);

Supported Provider Methods

The current extension supports:

• octra_requestAccounts
• octra_accounts
• octra_getBalance
• octra_chainId
• octra_network
• octra_networkId
• octra_networkInfo
• octra_permissions
• octra_switchNetwork
• octra_estimateFee
• octra_signMessage
• octra_signTransaction
• octra_sendTransaction
• octra_submitTransaction
• octra_callContract
• octra_sendContractTransaction
• octra_getContractReceipt

The SDK also exposes RFC-O-1 privacy method wrappers. The current extension intentionally rejects those dApp privacy requests until the external privacy transaction API is stable enough for third-party websites.

Amount Helpers

Octra uses 6 decimal places for OCT base units.

octToBaseUnits("1.5");       // "1500000"
baseUnitsToOct("1500000");   // "1.5"
decimalToBaseUnits("2.25", 9);

Transactions

sendTransaction, signTransaction, and estimateFee accept an OctraTransaction.

type OctraTransaction = {
  from?: string;
  to_?: string;
  to?: string;
  amount: string | number | bigint;
  nonce?: number;
  ou?: string | number | bigint;
  timestamp?: number;
  op_type?: string;
  encrypted_data?: string;
  message?: string;
};

The SDK normalizes to into to_, stringifies amount and ou, and defaults op_type to standard unless encrypted_data is present.

Contract Calls

Contract calls are submitted as Octra call transactions.

await fhex.sendTransaction({
  from: address,
  to_: tokenPoolAddress,
  amount: "0",
  ou: "1000",
  op_type: "call",
  encrypted_data: "swap_tokens_for_oct",
  message: JSON.stringify([rawTokenAmount])
});

Events

The SDK passes through provider events when the installed wallet emits them.

const stop = fhex.on("accountsChanged", accounts => {
  console.log(accounts);
});

stop();

Errors

Errors are normalized as FhexWalletError where possible.

try {
  await fhex.connect();
} catch (err) {
  console.error(err.code, err.message, err.data);
}

Common codes:

• 4001: user rejected or request aborted
• 4100: unauthorized
• 4900: wallet/provider unavailable
• -32602: invalid parameters
• -32603: internal wallet/provider error

Publishing

This sdk/ directory is standalone and can be pushed to its own GitHub repository.

cd sdk
npm install
npm run check
npm publish --access public

The package exposes:

• ESM: dist/index.mjs
• CommonJS: dist/index.cjs
• Browser script: dist/fhex-wallet-sdk.js
• Types: dist/index.d.ts