Cardano

Cardano integration via OneKey's CIP-30 compatible provider

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.

---

Quick Links

• API Reference

• Connecting

• Transactions

• Data Signing

---

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
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

  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

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/Method	Description
name	Wallet name ('OneKey')
icon	Wallet icon URL
apiVersion	API version
isEnabled()	Check if enabled
enable()	Request wallet access

dApp API (after enable)

Method	Description
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

Method	Description
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

Event	Description
accountChange	Account 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

Code	Description
-1	User rejected
-2	Account not found
-3	Invalid network

---

Using with Lucid

Lucid provides a simpler API:

npm install 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

// 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()