Developer Docs

Installation

Magic interacts with the Bitcoin blockchain via Magic’s extension NPM package @magic-ext/bitcoin.

NOTEBitcoin support requires @magic-ext/bitcoin v29.0.0 or higher. Bitcoin keys are held in Magic’s TEE, and the signing API changed in v29.0.0. Earlier versions are no longer supported.

npm install @magic-ext/bitcoin

yarn add @magic-ext/bitcoin

Initialization

JavaScript

import { Magic } from 'magic-sdk';
import { BitcoinExtension } from '@magic-ext/bitcoin';

const magic = new Magic('YOUR_API_KEY', {
  extensions: [
    new BitcoinExtension({
      rpcUrl: 'BTC_RPC_NODE_URL',
      network: 'testnet', // testnet or mainnet
    }),
  ],
});

Magic issues native SegWit (bech32) addresses. Wallets on mainnet are prefixed with bc1, and wallets on testnet are prefixed with tb1. Each network has its own wallet, so a user’s testnet address is not the same as their mainnet address.

Common Methods

Get Public Address

Retrieves the user’s Bitcoin address for the network the extension is configured with.

JavaScript

const publicAddress = await magic.bitcoin.getPublicAddress();

console.log(publicAddress); // => "tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"

Sign Transaction

Signs a Bitcoin transaction inside Magic’s TEE and resolves with a broadcast-ready transaction. You supply fully-formed inputs (the UTXOs to spend) and outputs. Coin selection, fees, and change are your responsibility — Magic signs exactly what you pass. The fee is the difference between the total input value and the total output value, so any amount you do not send back to your own address as change is paid to miners.

You choose the fee. Signing does not enforce a minimum or maximum transaction fee, or a dust threshold. It rejects transactions whose total output value exceeds their total input value. All input and output value fields are in BTC:fee = sum(inputs.value) - sum(outputs.value)Include every output, including change. Values must be non-negative BTC amounts representing whole satoshis (at most eight decimal places). Tiny floating-point arithmetic errors of up to 0.001 satoshi are tolerated; larger fractional-satoshi amounts are rejected. Calculate amounts in integer satoshis, then divide by 100_000_000 when passing them to this API. Check the resulting fee before signing, since any value left over becomes the miner fee.Use a fee estimate in sats per virtual byte (sats/vB) for your desired confirmation target. Relay and dust policies depend on the broadcasting node and output script type. Zero-fee, low-fee, or dust-output transactions can be signed but may be rejected by nodes or remain unconfirmed. Successful signing does not verify that the supplied UTXOs exist, are unspent, or have the claimed values. Your node’s testmempoolaccept RPC can check acceptance before broadcasting.

Magic does not broadcast the transaction. Submit the returned signedTransaction to the network yourself via your Bitcoin node or a broadcast API. Arguments

inputs (Array): The UTXOs to spend. Each input requires:
- txid (String): The transaction ID of the transaction that created the UTXO
- tx_num (Number): The output index (vout) of the UTXO within that transaction
- value (Number): The value of the UTXO in BTC, not satoshis. This is required — the TEE needs each input’s value to compute its SegWit (BIP143) sighash
- address (String, optional): The address the UTXO is locked to
outputs (Array): The outputs to create. Each output requires:
- address (String): The recipient address
- value (Number): The amount to send in BTC, not satoshis

Returns

Promise<BitcoinSignedTransaction>
- signedTransaction (String): The fully-signed, broadcast-ready transaction as hex
- transactionHash (String): The transaction hash (txid)

If you’re using TypeScript, @magic-ext/bitcoin exports these types directly: BitcoinTransactionInput, BitcoinTransactionOutput, BitcoinSignedTransaction, and BitcoinConfig.

JavaScript

import { Magic } from 'magic-sdk';
import { BitcoinExtension } from '@magic-ext/bitcoin';

const magic = new Magic('YOUR_API_KEY', {
  extensions: [
    new BitcoinExtension({
      rpcUrl: 'BTC_RPC_NODE_URL',
      network: 'testnet', // testnet or mainnet
    }),
  ],
});

const publicAddress = await magic.bitcoin.getPublicAddress();

// Example amounts only: choose the fee using current estimates and transaction size.
const inputSats = 200_000;
const recipientSats = 150_000;
const feeSats = 261;
const changeSats = inputSats - recipientSats - feeSats;

const { signedTransaction, transactionHash } = await magic.bitcoin.signTransaction(
  [
    {
      txid: 'fde789dad13b52e33229baed29b11d3e6f6dd306eb159865957dce13219bf85c',
      tx_num: 0,
      value: inputSats / 100_000_000,
    },
  ],
  [
    {
      address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx',
      value: recipientSats / 100_000_000,
    },
    {
      // Send the remainder back to yourself as change
      address: publicAddress,
      value: changeSats / 100_000_000,
    },
  ],
);

// Total in (0.002) - total out (0.00199739) = 0.00000261 BTC (261 sats) in fees

console.log('signed transaction', signedTransaction);
console.log('transaction hash', transactionHash);

Reveal Private Key

Displays an iframe revealing the user’s Bitcoin private key. See Key Export for more detail.

JavaScript

await magic.bitcoin.revealPrivateKey();

Resources

Bitcoin Developer Site

Embedded Wallets

Authentication

Wallets

SDKs

Blockchains

Bitcoin

Installation

Initialization

Common Methods

Get Public Address

Sign Transaction

Reveal Private Key

Resources

​Installation

​Initialization

​Common Methods

​Get Public Address

​Sign Transaction

​Reveal Private Key

​Resources

Installation

Initialization

Common Methods

Get Public Address

Sign Transaction

Reveal Private Key

Resources