Guide

Working with Runes

Learn how to interact with Bitcoin Runes using LaserEyes - fetch balances, send tokens, and more.

LaserEyes provides comprehensive support for Bitcoin Runes, allowing you to easily fetch balances, send tokens, and interact with the Runes protocol through a unified interface.

Key Features

Fetch Rune Balances

Retrieve Rune balances for any Bitcoin address with support for multiple data sources.

Send Runes

Securely transfer Runes between addresses with built-in PSBT support.

Rich Metadata

Access comprehensive Rune metadata including name, symbol, decimals, and supply information.

Safe Transfers

Built-in safety checks and validations for secure Rune transfers.

The Rune Balance Type

Rune Balance Interface

type OrdRuneBalance = {
  name: string;      // The name of the rune
  balance: string;   // The balance amount
  symbol: string;    // The rune symbol
}

Fetching Rune Balances

Example

import { useLaserEyes } from '@omnisat/lasereyes-react'
import { useState, useEffect } from 'react'

function RuneBalances() {
  const { getAddressRunesBalances } = useLaserEyes()
  const [balances, setBalances] = useState([])
  const [loading, setLoading] = useState(false)

  useEffect(() => {
    const fetchBalances = async () => {
      try {
        setLoading(true)
        const results = await getAddressRunesBalances('bc1p...')
        setBalances(results)
      } catch (error) {
        console.error('Failed to fetch balances:', error)
      } finally {
        setLoading(false)
      }
    }

    fetchBalances()
  }, [])

  if (loading) return <div>Loading rune balances...</div>

  return (
    <div className="space-y-4">
      {balances.map(rune => (
        <div key={rune.name} className="p-4 border rounded">
          <h3 className="font-bold">{rune.name}</h3>
          <p>Balance: {rune.balance} {rune.symbol}</p>
        </div>
      ))}
    </div>
  )
}

Sending Runes

Example

import { useLaserEyes } from '@omnisat/lasereyes-react'
import { useState } from 'react'
import { RUNES } from '@omnisat/lasereyes-core'

function SendRune() {
  const { send } = useLaserEyes()
  const [sending, setSending] = useState(false)

  const handleSend = async () => {
    try {
      setSending(true)
      
      // Send runes to an address
      const txId = await send(RUNES, {
        runeName: 'PEPE',
        amount: '1000',
        toAddress: 'bc1p...'
      })

      console.log('Transaction ID:', txId)
    } catch (error) {
      console.error('Failed to send:', error)
    } finally {
      setSending(false)
    }
  }

  return (
    <button 
      onClick={handleSend}
      disabled={sending}
      className="px-4 py-2 bg-purple-500 text-white rounded"
    >
      {sending ? 'Sending...' : 'Send Runes'}
    </button>
  )
}

Best Practices

1. Error Handling

Always implement proper error handling for Rune operations. Network issues, insufficient balances, or wallet rejections should be handled gracefully.

2. Loading States

Show appropriate loading states during Rune operations. Both fetching balances and sending can take time to complete.

3. Balance Validation

Always validate Rune balances before attempting transfers. Check both the balance amount and if the user owns the Rune.

4. Data Source Fallbacks

Consider implementing fallback data sources for Rune operations. LaserEyes supports multiple data providers to ensure reliability.

Complete Example

Runes Dashboard Example

import { useLaserEyes } from '@omnisat/lasereyes-react'
import { useState, useEffect } from 'react'
import { RUNES } from '@omnisat/lasereyes-core'

function RunesDashboard() {
  const { getAddressRunesBalances, send, address } = useLaserEyes()
  const [balances, setBalances] = useState([])
  const [loading, setLoading] = useState(false)
  const [sending, setSending] = useState(false)
  const [selectedRune, setSelectedRune] = useState(null)
  const [amount, setAmount] = useState('')
  const [recipient, setRecipient] = useState('')

  useEffect(() => {
    if (address) {
      fetchBalances()
    }
  }, [address])

  const fetchBalances = async () => {
    try {
      setLoading(true)
      const results = await getAddressRunesBalances(address)
      setBalances(results)
    } catch (error) {
      console.error('Failed to fetch balances:', error)
    } finally {
      setLoading(false)
    }
  }

  const handleSend = async (e) => {
    e.preventDefault()
    if (!selectedRune || !amount || !recipient) return

    try {
      setSending(true)
      const txId = await send(RUNES, {
        runeName: selectedRune,
        amount,
        toAddress: recipient
      })
      
      console.log('Transaction ID:', txId)
      // Refresh balances after sending
      await fetchBalances()
      
      // Reset form
      setSelectedRune(null)
      setAmount('')
      setRecipient('')
    } catch (error) {
      console.error('Failed to send:', error)
    } finally {
      setSending(false)
    }
  }

  if (loading) return <div>Loading rune balances...</div>

  return (
    <div className="space-y-8">
      {/* Balances Display */}
      <div className="grid gap-4 sm:grid-cols-2">
        {balances.map(rune => (
          <div 
            key={rune.name}
            className="p-4 border rounded hover:border-purple-500/30 cursor-pointer"
            onClick={() => setSelectedRune(rune.name)}
          >
            <h3 className="font-bold">{rune.name}</h3>
            <p>Balance: {rune.balance} {rune.symbol}</p>
          </div>
        ))}
      </div>

      {/* Send Form */}
      <form onSubmit={handleSend} className="space-y-4">
        <div>
          <label className="block mb-2">Selected Rune</label>
          <input
            type="text"
            value={selectedRune || ''}
            readOnly
            className="w-full p-2 border rounded"
          />
        </div>

        <div>
          <label className="block mb-2">Amount</label>
          <input
            type="text"
            value={amount}
            onChange={(e) => setAmount(e.target.value)}
            className="w-full p-2 border rounded"
            placeholder="Enter amount"
          />
        </div>

        <div>
          <label className="block mb-2">Recipient Address</label>
          <input
            type="text"
            value={recipient}
            onChange={(e) => setRecipient(e.target.value)}
            className="w-full p-2 border rounded"
            placeholder="Enter recipient address"
          />
        </div>

        <button
          type="submit"
          disabled={sending || !selectedRune || !amount || !recipient}
          className="px-4 py-2 bg-purple-500 text-white rounded disabled:opacity-50"
        >
          {sending ? 'Sending...' : 'Send Runes'}
        </button>
      </form>
    </div>
  )
}

Inscriptions

BRC-20