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: "hfhe_v1|base64..." }

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

Returns	Type	Description
ciphertext	string	HFHE v1 prefixed PVAC ciphertext

octra_pvac_encryptProve

Encrypts a value and generates a Pedersen commitment + bound zero proof in a single approved operation. Optionally includes a range proof. Routed through the accelerator when available.

const result = await window.octra.request({
  method: 'octra_pvac_encryptProve',
  params: [{ value: 1000000, rangeProof: true }],
});
// { ciphertext, amount_commitment, zero_proof, blinding, range_proof? }

Param	Type	Description
value required	number	Plaintext value (in smallest unit)
rangeProof	boolean	If true, also generates a range proof on the ciphertext

Returns	Type	Description
ciphertext	string	HFHE v1 prefixed PVAC ciphertext
amount_commitment	string	Base64 Pedersen commitment to the value
zero_proof	string	Base64 bound zero proof
blinding	string	Base64 blinding factor (for commitment verification)
range_proof	string	Base64 range proof (only if rangeProof=true)

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: "rp_v1|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	Prefixed base64 range proof

Homomorphic Arithmetic

Raw arithmetic on encrypted ciphertexts. No user approval required — these are fast WASM operations. Ciphertexts passed as arguments should be raw base64 (strip the hfhe_v1| prefix first).

octra_pvac_ctAdd

Add two ciphertexts: result = a + b

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

Param	Type	Description
a required	string	Base64 ciphertext A (raw, no prefix)
b required	string	Base64 ciphertext B (raw, no prefix)

Returns	Type	Description
ciphertext	string	Base64 result ciphertext

octra_pvac_ctSub

Subtract two ciphertexts: result = a - b

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

Param	Type	Description
a required	string	Base64 ciphertext A (raw, no prefix)
b required	string	Base64 ciphertext B (raw, no prefix)

Returns	Type	Description
ciphertext	string	Base64 result ciphertext

octra_pvac_ctMul

Multiply two ciphertexts: result = a * b

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

Param	Type	Description
a required	string	Base64 ciphertext A (raw, no prefix)
b required	string	Base64 ciphertext B (raw, no prefix)

Returns	Type	Description
ciphertext	string	Base64 result ciphertext

octra_pvac_ctAddConst

Add a plaintext constant to a ciphertext: result = ct + k

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

Param	Type	Description
ciphertext required	string	Base64 ciphertext (raw, no prefix)
value required	number	Plaintext constant to add

Returns	Type	Description
ciphertext	string	Base64 result ciphertext

octra_pvac_ctSubConst

Subtract a plaintext constant from a ciphertext: result = ct - k

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

Param	Type	Description
ciphertext required	string	Base64 ciphertext (raw, no prefix)
value required	number	Plaintext constant to subtract

Returns	Type	Description
ciphertext	string	Base64 result ciphertext

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

octra_pvac_stealthTransfer

Encrypts a transfer amount, homomorphically subtracts it from the sender's encrypted balance, and generates range proofs on both the delta and new balance — all in a single approved operation. Used by dApps implementing custom encrypted tokens.

const result = await window.octra.request({
  method: 'octra_pvac_stealthTransfer',
  params: [{
    balance: 'base64...',   // sender's encrypted balance (raw, no prefix)
    amount: 100,            // amount to transfer
    balanceValue: 1000,     // sender's known plaintext balance
  }],
});
// { ciphertext, amount_commitment, zero_proof, blinding,
//   new_balance, range_proof_delta, range_proof_balance, new_balance_value }

Param	Type	Description
balance required	string	Sender's encrypted balance (raw base64, no hfhe_v1| prefix)
amount required	number	Amount to transfer (plaintext)
balanceValue required	number	Sender's known plaintext balance (for range proof)

Returns	Type	Description
ciphertext	string	HFHE v1 prefixed delta ciphertext
amount_commitment	string	Pedersen commitment to the transfer amount
zero_proof	string	Bound zero proof for the delta
blinding	string	Blinding factor for the commitment
new_balance	string	Base64 new encrypted balance ciphertext
range_proof_delta	string	Range proof on the delta ciphertext
range_proof_balance	string	Range proof on the new balance ciphertext
new_balance_value	number	New plaintext balance (for local tracking)

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

zkTLS

zkTLS lets DApps generate zero-knowledge proofs of TLS sessions. The wallet records a TLS handshake and the Octane Accelerator (Jolt zkVM) proves it locally — no data leaves the user's machine. Requires the Octane Accelerator to be running.

octra_requestZktlsProofJolt

Records a TLS session to the given URL and generates a zero-knowledge proof of the response using Jolt. Proofs are cached by ID — subsequent calls with the same ID return instantly.

const result = await window.octra.request({
  method: 'octra_requestZktlsProofJolt',
  params: [{
    url: 'https://api.github.com/zen',
    headers: { Accept: 'application/json' },
    id: 'github-zen-proof',
    records: [0, 1],
  }],
});
// { proof, public_inputs, url, status, _cached?, _cacheAge? }

Param	Type	Description
url required	string	URL to fetch and prove
headers	object	Custom HTTP headers (JSON object)
id	string	Unique claim ID for caching. Same ID + URL returns cached proof.
records	number[]	TLS record indices to include in the proof (default: all)
regenerate	boolean	Force regeneration, skip cache

Returns	Type	Description
proof	string	Base64-encoded Jolt proof blob
public_inputs	object	Public inputs (URL hash, response digest, record metadata)
url	string	The proven URL
status	string	Proof status ("verified" or "error")
_cached	boolean	True if this was a cached proof
_cacheAge	number	Age of cached proof in seconds

💡 Try it live: Open the Demo App → — section 11 exercises the full zkTLS flow interactively.