Skip to Content

Cardano

Integrate Cardano blockchain using OneKey’s CIP-30 compatible provider. Access via window.cardano.onekey or window.cardano.nami.

OneKey implements CIP-30 (Cardano dApp Connector), ensuring compatibility with all Cardano dApps. It also provides Nami wallet compatibility.



Provider Detection

// OneKey provides both onekey and nami interfaces const onekey = window.cardano?.onekey const nami = window.cardano?.nami // Check availability if (!onekey) { throw new Error('OneKey Cardano provider not detected') } // Get wallet info console.log('Name:', onekey.name) // 'OneKey' console.log('API Version:', onekey.apiVersion) // '0.1.0' console.log('Icon:', onekey.icon)

Quick Start

Enable Wallet

// Request wallet access const api = await window.cardano.onekey.enable() // Now you can use the full API const networkId = await api.getNetworkId() console.log('Network:', networkId === 1 ? 'Mainnet' : 'Testnet')

Check if Enabled

const isEnabled = await window.cardano.onekey.isEnabled() if (isEnabled) { const api = await window.cardano.onekey.enable() // Use API... }

Account Information

Get Network ID

const api = await window.cardano.onekey.enable() const networkId = await api.getNetworkId() // 0 = Testnet, 1 = Mainnet console.log('Network:', networkId)

Get Balance

const balance = await api.getBalance() // Returns CBOR-encoded value (hex string) console.log('Balance (CBOR):', balance) // Decode using cardano-serialization-lib import { Value } from '@emurgo/cardano-serialization-lib-browser' const value = Value.from_bytes(Buffer.from(balance, 'hex')) const lovelace = value.coin().to_str() console.log('Balance:', parseInt(lovelace) / 1000000, 'ADA')

Get Addresses

// Get used addresses (addresses with transaction history) const usedAddresses = await api.getUsedAddresses() console.log('Used addresses:', usedAddresses) // Get unused addresses (fresh addresses) const unusedAddresses = await api.getUnusedAddresses() console.log('Unused addresses:', unusedAddresses) // Get change address const changeAddress = await api.getChangeAddress() console.log('Change address:', changeAddress) // Get reward/staking addresses const rewardAddresses = await api.getRewardAddresses() console.log('Reward addresses:', rewardAddresses)

Get UTxOs

// Get all UTxOs const utxos = await api.getUtxos() console.log('UTxOs:', utxos) // Get UTxOs with minimum amount const utxosWithAmount = await api.getUtxos( '1000000' // Minimum 1 ADA in lovelace (CBOR encoded) ) // With pagination const paginatedUtxos = await api.getUtxos(undefined, { page: 0, limit: 10, })

Transactions

Sign Transaction

// transaction should be CBOR-encoded hex string const signedTx = await api.signTx(transactionCbor, partialSign) // partialSign: boolean // - false: sign all inputs owned by wallet // - true: sign only inputs explicitly owned (for multi-sig) console.log('Signed TX:', signedTx)

Submit Transaction

// Submit signed transaction const txHash = await api.submitTx(signedTransactionCbor) console.log('Transaction hash:', txHash)

Complete Transaction Flow

import { TransactionBuilder, TransactionBuilderConfigBuilder, LinearFee, BigNum, Address, TransactionOutput, Value, } from '@emurgo/cardano-serialization-lib-browser' async function sendAda(recipientAddress, amountLovelace) { const api = await window.cardano.onekey.enable() // Get UTxOs const utxos = await api.getUtxos() const changeAddress = await api.getChangeAddress() // Build transaction const txBuilder = TransactionBuilder.new( TransactionBuilderConfigBuilder.new() .fee_algo(LinearFee.new( BigNum.from_str('44'), BigNum.from_str('155381') )) .pool_deposit(BigNum.from_str('500000000')) .key_deposit(BigNum.from_str('2000000')) .max_value_size(5000) .max_tx_size(16384) .coins_per_utxo_byte(BigNum.from_str('4310')) .build() ) // Add inputs from UTxOs utxos.forEach(utxo => { // Add UTxO as input... }) // Add output txBuilder.add_output( TransactionOutput.new( Address.from_bech32(recipientAddress), Value.new(BigNum.from_str(amountLovelace)) ) ) // Set change address txBuilder.add_change_if_needed(Address.from_bech32(changeAddress)) // Build transaction const tx = txBuilder.build_tx() const txCbor = Buffer.from(tx.to_bytes()).toString('hex') // Sign const signedTxCbor = await api.signTx(txCbor, false) // Submit const txHash = await api.submitTx(signedTxCbor) console.log('TX Hash:', txHash) return txHash }

Data Signing

Sign Data (CIP-8)

Sign arbitrary data for authentication:

const api = await window.cardano.onekey.enable() const addresses = await api.getUsedAddresses() const address = addresses[0] // Message to sign const payload = Buffer.from('Hello Cardano!').toString('hex') const signature = await api.signData(address, payload) console.log({ signature: signature.signature, // COSE_Sign1 signature key: signature.key, // COSE_Key public key })

Verify Signature

import { COSESign1, COSEKey } from '@emurgo/cardano-message-signing-browser' const coseSign1 = COSESign1.from_bytes( Buffer.from(signature.signature, 'hex') ) const coseKey = COSEKey.from_bytes( Buffer.from(signature.key, 'hex') ) // Get the signed payload const signedPayload = coseSign1.payload() // Verify signature const publicKey = coseKey.header(0) // Get Ed25519 key // Verification logic...

Event Handling

Listen for Account Changes

const api = await window.cardano.onekey.enable() // Nami-compatible event API api.experimental.on('accountChange', (addresses) => { console.log('Account changed:', addresses) })

API Reference

Wallet Interface (CIP-30)

Property/MethodDescription
nameWallet name (‘OneKey’)
iconWallet icon URL
apiVersionAPI version
isEnabled()Check if enabled
enable()Request wallet access

dApp API (after enable)

MethodDescription
getNetworkId()Get network (0=testnet, 1=mainnet)
getBalance()Get total balance (CBOR)
getUtxos(amount?, paginate?)Get UTxOs
getUsedAddresses()Get used addresses
getUnusedAddresses()Get unused addresses
getChangeAddress()Get change address
getRewardAddresses()Get staking addresses
signTx(tx, partialSign?)Sign transaction
signData(addr, payload)Sign data (CIP-8)
submitTx(tx)Submit transaction

Experimental API

MethodDescription
experimental.getCollateral()Get collateral UTxOs
experimental.on(event, cb)Subscribe to events
experimental.off()Unsubscribe

Types

type Cbor = string // Hex-encoded CBOR interface Paginate { page: number limit: number } interface Cip30DataSignature { signature: string // COSE_Sign1 hex key: string // COSE_Key hex } type NetworkId = 0 | 1 // 0=testnet, 1=mainnet

Events

EventDescription
accountChangeAccount changed

Error Handling

try { const api = await window.cardano.onekey.enable() } catch (error) { if (error.code === -1) { console.log('User rejected connection') } else if (error.code === -2) { console.log('Account not found') } else { console.error('Error:', error.message) } }

Common Errors

CodeDescription
-1User rejected
-2Account not found
-3Invalid network

Using with Lucid

Lucid  provides a simpler API:

npm install lucid-cardano
import { Lucid } from 'lucid-cardano' // Initialize Lucid with OneKey const lucid = await Lucid.new( new Blockfrost('https://cardano-mainnet.blockfrost.io/api', 'your-api-key'), 'Mainnet' ) // Connect OneKey const api = await window.cardano.onekey.enable() lucid.selectWallet(api) // Send ADA const tx = await lucid .newTx() .payToAddress('addr1...', { lovelace: 5000000n }) .complete() const signedTx = await tx.sign().complete() const txHash = await signedTx.submit() console.log('TX Hash:', txHash)

Using with Mesh

Mesh  is another popular Cardano SDK:

npm install @meshsdk/core
import { BrowserWallet, Transaction } from '@meshsdk/core' // Connect to OneKey const wallet = await BrowserWallet.enable('onekey') // Get wallet info const balance = await wallet.getBalance() const addresses = await wallet.getUsedAddresses() // Build and send transaction const tx = new Transaction({ initiator: wallet }) .sendLovelace('addr1...', '5000000') const unsignedTx = await tx.build() const signedTx = await wallet.signTx(unsignedTx) const txHash = await wallet.submitTx(signedTx)

Nami Compatibility

OneKey provides Nami wallet compatibility:

// Access via Nami interface const nami = window.cardano.nami const api = await nami.enable() // Same API as OneKey const balance = await api.getBalance()
Last updated on