Wallet API Reference

The Octane wallet exposes a JSON-RPC API via window.octra. DApps call methods using window.octra.request({ method, params }).

This is the same provider pattern used by MetaMask and other Ethereum wallets.

// Basic usage
const accounts = await window.octra.request({
  method: 'octra_requestAccounts',
});
console.log(accounts[0]); // "octAbc..."

💡 Live example: Open the PVAC Proof Demo → — an interactive page that exercises encrypt, decrypt, range proof, and commitment APIs against your wallet.

Authentication

When a Dapp calls a method, the extension prompts the user for approval (for sensitive operations like signing or sending).

It's usually best to call octra_requestAccounts first to establish a connection and get the user's address.

Error Handling

All methods reject with an Error if something goes wrong. The wallet returns structured error objects with an error string field. Handle them in a try/catch:

try {
  const result = await window.octra.request({ method: 'octra_balance' });
} catch (e) {
  console.log(e.message); // error string from the table below
}

Connection Errors

Error	Description
User rejected connection	User denied the connection approval popup
User rejected request	User denied a generic approval popup (PVAC encrypt, decrypt, range proof, etc.)

Wallet State Errors

Error	Description
locked	Wallet is locked — call octra_requestAccounts to trigger unlock
Wallet is locked	Same as above, used in dApp context
no wallet	Extension installed but no wallet has been created or imported
PVAC derivation failed	Failed to derive privacy keys from the seed

Transaction Errors

Error	Description
User rejected transaction	User denied the send transaction approval popup
User rejected signature request	User denied the message signing approval popup
User rejected contract call	User denied the contract call approval popup
User rejected decrypt request	User denied the PVAC decrypt approval popup
invalid amount	Amount is zero, negative, or not a valid number
Invalid contract call data	Malformed calldata passed to octra_contractCall

Balance & Privacy Errors

Error	Description
missing value	Required value parameter not provided (PVAC encrypt)
Missing ciphertext	Ciphertext not provided for decrypt operation
No encrypted balance	Shield/unshield attempted but no on-chain encrypted balance exists
Insufficient encrypted balance: have X, need Y	Unshield or stealth send amount exceeds the encrypted balance

Stealth Transfer Errors

Error	Description
recipient_no_pvac	Recipient has no PVAC public key registered on-chain — they need funds to receive stealth sends
Recipient has no public key registered	Recipient has never made a transaction — they must transact at least once
Invalid recipient public key	Recipient's registered public key is malformed

Network Errors

Error	Description
Tor proxy not reachable at 127.0.0.1:9050	Tor routing enabled but Tor Browser is not running

Connection

octra_requestAccounts

Requests permission to connect. Opens an approval popup in the wallet extension. Returns an array with the active account address.

const accounts = await window.octra.request({
  method: 'octra_requestAccounts',
});
// ["octAbc123..."]

Returns	Type	Description
accounts	string[]	Array with one address string

octra_accounts

Returns currently connected accounts without prompting. Returns empty array if not connected.

const accounts = await window.octra.request({
  method: 'octra_accounts',
});
// ["octAbc123..."] or []

Returns	Type	Description
accounts	string[]	Array of connected addresses (empty if not connected)

octra_disconnect

Disconnects the Dapp from the wallet. Subsequent calls to octra_accounts will return an empty array.

Balances

octra_balance

Returns the public (unencrypted) balance for the connected account.

const result = await window.octra.request({
  method: 'octra_balance',
});
// { formatted: "1.500000", raw: "1500000" }

Returns	Type	Description
formatted	string	Human-readable balance (e.g. "1.500000")
raw	string	Raw balance in smallest unit (microOCT)

octra_encryptedBalance

Returns the encrypted (on-chain) private balance ciphertext. Requires the wallet to be unlocked.

const result = await window.octra.request({
  method: 'octra_encryptedBalance',
});
// { cipher: "hfhe_v1|...", has_pvac_pubkey: true }

Returns	Type	Description
cipher	string	HFHE v1 prefixed ciphertext (base64), or "0" if no balance
has_pvac_pubkey	boolean	Whether the account has a PVAC public key registered on-chain

octra_decryptedBalance

Decrypts the private balance using PVAC keys and returns the human-readable value. This is an expensive operation — the wallet caches the result.

const result = await window.octra.request({
  method: 'octra_decryptedBalance',
});
// { balance: "1000000" }

Returns	Type	Description
balance	string	Decrypted balance as a string (microOCT)

octra_tokensByAddress

Returns OCS-01 tokens held by the given address.

const tokens = await window.octra.request({
  method: 'octra_tokensByAddress',
});
// [{ contract: "oct...", symbol: "wOCT", balance: "5000000" }]

Returns	Type	Description
tokens	object[]	Array of token objects
tokens[].contract	string	Token contract address
tokens[].symbol	string	Token symbol
tokens[].balance	string	Token balance (raw)

Transactions

octra_sendTransaction

Sends a public transaction. Opens an approval popup showing the recipient, amount, and fee.

const result = await window.octra.request({
  method: 'octra_sendTransaction',
  params: [{
    to: 'octRecipient123...',
    amount: '1.5',
  }],
});
// { hash: "abc123..." }

Param	Type	Description
to required	string	Recipient address
amount required	string	Amount in OCT (human-readable, e.g. "1.5")
fee	string	Custom fee override

Returns	Type	Description
hash	string	Transaction hash

octra_signMessage

Signs an arbitrary message with the wallet's ed25519 key. Opens an approval popup.

const result = await window.octra.request({
  method: 'octra_signMessage',
  params: ['Hello, Octra!'],
});
// { signature: "base64..." }

Returns	Type	Description
signature	string	Base64-encoded ed25519 signature

octra_contractCall

Calls a smart contract method on-chain. Opens an approval popup.

const result = await window.octra.request({
  method: 'octra_contractCall',
  params: [{
    contract: 'octContractAddr...',
    method: 'transfer',
    params: ['octRecipient...', 1000000],
  }],
});

Param	Type	Description
contract required	string	Contract address
method required	string	Method name to call
params	any[]	Method arguments

Returns	Type	Description
result	object	Contract call result (shape depends on the contract)

Privacy (PVAC)

PVAC (Pedersen Verifiable Arithmetic Commitments) is the privacy primitive used by Octra. These methods let Dapps work with encrypted values, generate commitments and proofs — all handled by the wallet's crypto layer.

octra_pvac_encrypt

Encrypts a plaintext value into a PVAC ciphertext. Uses the wallet's PVAC public key.

const result = await window.octra.request({
  method: 'octra_pvac_encrypt',
  params: [{ value: 1000000 }],
});
// { ciphertext: "base64..." }

Param	Type	Description
value required	number	Plaintext value (in smallest unit)

Returns	Type	Description
ciphertext	string	Base64-encoded PVAC ciphertext

octra_pvac_decrypt

Decrypts a PVAC ciphertext back to its plaintext value. Requires wallet unlock and user approval.

const result = await window.octra.request({
  method: 'octra_pvac_decrypt',
  params: [{ ciphertext: 'base64...' }],
});
// { value: 1000000 }

Param	Type	Description
ciphertext required	string	Base64-encoded PVAC ciphertext to decrypt

Returns	Type	Description
value	number	Decrypted plaintext value

octra_pvac_commit

Creates a Pedersen commitment to a value with a random blinding factor. Used by the faucet and other protocols to prove wallet ownership without revealing the value.

const result = await window.octra.request({
  method: 'octra_pvac_commit',
  params: [{ value: 3000000 }],
});
// { commitment: "base64..." }

Param	Type	Description
value required	number	Value to commit to (in smallest unit)

Returns	Type	Description
commitment	string	Base64-encoded Pedersen commitment

octra_pvac_rangeProof

Generates a zero-knowledge range proof that a ciphertext encrypts a specific non-negative value. Required for shield/unshield operations.

const result = await window.octra.request({
  method: 'octra_pvac_rangeProof',
  params: [{
    ciphertext: 'base64...',
    value: 1000000,
  }],
});
// { proof: "base64..." }

Param	Type	Description
ciphertext required	string	Base64-encoded PVAC ciphertext
value required	number	The value the ciphertext is expected to encrypt

Returns	Type	Description
proof	string	Base64-encoded range proof

Stealth Transfers

octra_stealth_send

Sends a private (stealth) transfer to another account. The amount is encrypted on-chain — only the sender and recipient can see it. The recipient discovers the payment by scanning for stealth-tagged outputs.

const result = await window.octra.request({
  method: 'octra_stealth_send',
  params: [{
    to: 'octRecipient...',
    amount: '100',
  }],
});
// { jobId: "uuid..." }

Stealth sends are bucketed — the amount must be one of: 1, 10, 100, 1000, 10000, 100000, 1000000 OCT.

Param	Type	Description
to required	string	Recipient address
amount required	string	Amount in OCT (must be a bucket value)

Returns	Type	Description
jobId	string	Job ID to track the stealth send progress

Network

octra_getNetworkInfo

Returns the current network configuration (mainnet vs devnet, RPC URL).

const info = await window.octra.request({
  method: 'octra_getNetworkInfo',
});
// { name: "mainnet", chainId: "octra-mainnet-1", rpcUrl: "https://octra.network/rpc" }

Returns	Type	Description
name	string	Network name ("mainnet" or "devnet")
chainId	string	Chain identifier
rpcUrl	string	Current RPC endpoint URL