Ramps: Onboarding & Offboarding

Advanced feature. Native ramps require onchain transactions, confirmation waits, and minimum amounts that account for Bitcoin fees.

Ramps connect confirmed Bitcoin outputs with Arkade transaction paths. The SDK exposes two main processes:

Onboarding (Boarding) - Commit a confirmed Bitcoin output to a Batch Output and create an Arkade wallet position.
Offboarding (Exiting) - Create a conventional Bitcoin output through collaborative withdrawal or an available unilateral path.

Onboarding (Boarding)

Boarding spends a confirmed Bitcoin output into the batch process and creates a wallet output rooted in a Bitcoin-confirmed Batch Output. The SDK represents that output as a Vtxo object.

Boarding Address

A boarding address is a 2-of-2 Taproot address that prevents the funding output from being double-spent during onboarding.

The Boarding Process

Generate a boarding address

Get a boarding address from your wallet:

import { Wallet, MnemonicIdentity } from '@arkade-os/sdk'

const identity = MnemonicIdentity.fromMnemonic(mnemonic)
const wallet = await Wallet.create({
  identity
})

const boardingAddress = await wallet.getBoardingAddress()
console.log('Boarding Address:', boardingAddress)

Send Bitcoin onchain

Fund the address from a Bitcoin wallet and wait for confirmation.

This is your first onchain transaction. Standard network fees apply.

Initiate the boarding settlement

Once confirmed, settle the boarding UTXO to your Arkade wallet:

import { Ramps } from '@arkade-os/sdk'

const info = await wallet.arkProvider.getInfo();
// => ArkInfo object including 'fees' object

const onboardTxid = await new Ramps(wallet).onboard(info.fees)
console.log('Onboarding transaction ID:', onboardTxid)

Arkade Server processes

The operator includes the output in a Commitment Transaction.

This is the second onchain transaction.

Receive the Arkade output

After confirmation, the SDK exposes the resulting output for cooperative transactions.

Boarding requires at least two onchain transactions plus confirmation waits.

Offboarding (Collaborative Exit)

Collaborative offboarding uses eligible Arkade outputs as inputs and creates a conventional Bitcoin output at the requested destination. This is the preferred native withdrawal path while the operator is available.

The Offboarding Process

Specify your destination

Set the Bitcoin address and amount:

const destinationAddress = "bc1q..." // Your onchain Bitcoin address
const amount = 50000 // Amount in sats (optional, undefined = exit all)

Request the offboard

Request the output; the SDK selects eligible inputs:

import { Wallet, MnemonicIdentity } from '@arkade-os/sdk'

const identity = MnemonicIdentity.fromMnemonic(mnemonic)
const wallet = await Wallet.create({
  identity
})
const info = await wallet.arkProvider.getInfo();
// => ArkInfo object including 'fees' object

const exitTxid = await new Ramps(wallet).offboard(
  destinationAddress,
  info.fees,
  amount
);
console.log('Exit transaction ID:', exitTxid)

Server processes

The operator includes the request in a Commitment Transaction.

Receive onchain Bitcoin

Wait for the destination output to confirm.

Collaborative withdrawal batches multiple requests into one transaction, which generally reduces confirmation steps and per-user Bitcoin fees while the operator is available.

Unilateral Exit

An eligible output can provide a unilateral Bitcoin path that does not require operator cooperation after its script conditions are met. This workflow can be substantially more expensive and complex than collaborative withdrawal.

Consider unilateral recovery when:

The operator is permanently unavailable
You cannot reach the server for collaborative exit
The selected output exposes a valid unilateral path

Verify the output state before starting. Recoverable, expired, swept, and sub-dust positions can require a cooperative batch process. An available unilateral path can require multiple sequential Bitcoin transactions and substantial fees.

The Unilateral Exit Process

Create and fund an onchain wallet

Unilateral exit requires unrolling virtual transactions onchain. Each transaction needs miner fees paid via P2A outputs.

// Create an onchain wallet to pay for miner fees
const onchainWallet = new OnchainWallet(wallet.identity, 'bitcoin');
console.log("Fund this address:", onchainWallet.address)

Send Bitcoin to this address to cover transaction fees for the unroll process.

Publish the transaction path

Unrolling publishes the applicable presigned Bitcoin transactions in sequence, with confirmation waits between the required steps.

const outpoint = { txid: 'your_vtxo_txid', vout: 0 };
const session = await Unroll.Session.create(
  outpoint,
  onchainWallet,              // pays miner fees
  onchainWallet.provider,     // onchain explorer
  wallet.indexerProvider      // Arkade indexer for virtual txs
);

// Execute the unroll process step by step
for await (const step of session) {
  switch (step.type) {
    case Unroll.StepType.WAIT:
      console.log(`Waiting for ${step.txid} to confirm`);
      break;
    case Unroll.StepType.UNROLL:
      console.log(`Broadcasting ${step.tx.id}`);
      break;
    case Unroll.StepType.DONE:
      console.log(`Unroll complete for ${step.vtxoTxid}`);
      break;
  }
}

Wait for CSV locktime

After unrolling, wait for the CHECKSEQUENCEVERIFY (CSV) relative timelock before spending the final output.

Complete the exit

Once the locktime is reached, claim your Bitcoin:

await Unroll.completeUnroll(
  wallet,                  // your Arkade wallet
  [vtxo.txid],            // VTXOs to complete
  onchainWallet.address   // where to receive your Bitcoin
);

See Unilateral Exit for path requirements, timelocks, fees, and recovery qualifications.

Related: VTXO management, Lightning payments, and settlement.

Getting Started

Bitcoin

Advanced Features

Ramps: Onboarding & Offboarding

Onboarding (Boarding)

Boarding Address

The Boarding Process

Offboarding (Collaborative Exit)

The Offboarding Process

Unilateral Exit

The Unilateral Exit Process

​Onboarding (Boarding)

​Boarding Address

​The Boarding Process

​Offboarding (Collaborative Exit)

​The Offboarding Process

​Unilateral Exit

​The Unilateral Exit Process

Onboarding (Boarding)

Boarding Address

The Boarding Process

Offboarding (Collaborative Exit)

The Offboarding Process

Unilateral Exit

The Unilateral Exit Process