Detect Deposits

Assets arrive at an Arkade address the same way BTC does: on a virtual output. Each virtual output lists the assets it holds in its assets field. To detect deposits of one asset, watch for virtual outputs that hold it. Then confirm each deposit in the transaction history before you credit it.

Setup

Import the SDK and create a wallet:

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

const identity = MnemonicIdentity.fromMnemonic("abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about")

const wallet = await Wallet.create({
  identity,
  arkProvider: new RestArkProvider('https://arkade.computer'),
})

// share this address to receive deposits
const depositAddress = await wallet.getAddress()

Verify the asset before you accept deposits of it, and filter by its asset ID.

List Asset Outputs

One virtual output can hold more than one asset. This helper returns one entry for each virtual output that holds the asset:

const findAsset = (outputs: ExtendedVirtualCoin[], assetId: string) =>
  outputs.flatMap(({ txid, vout, virtualStatus, assets }) =>
    (assets ?? [])
      .filter((asset) => asset.assetId === assetId)
      .map(({ amount }) => ({ txid, vout, state: virtualStatus.state, amount })),
  )

Read the virtual outputs that already hold the asset:

const outputs = await wallet.getVtxos({ withRecoverable: true })

console.log(findAsset(outputs, assetId))
// [{ txid: '...', vout: 0, state: 'settled', amount: 1000n }]

withRecoverable: true also returns virtual outputs that need recovery before you can spend them. Use notifyIncomingFunds() to receive an event when a virtual output arrives at or leaves the address:

const stop = await wallet.notifyIncomingFunds((event) => {
  // boarding outputs (`utxo` events) don't carry assets
  if (event.type === 'utxo') return

  const received = findAsset(event.newVtxos, assetId)
  if (received.length) console.log('New asset outputs:', received)

  const spent = findAsset(event.spentVtxos, assetId)
  if (spent.length) console.log('Spent asset outputs:', spent)
})

// stop the subscription when you shut down
stop()

newVtxos lists every new virtual output at the address. This includes change from your own sends and virtual outputs renewed in a batch swap. Don’t credit deposits from newVtxos.

Credit Deposits

Use the notification as a signal, then read the transaction history. The history doesn’t list change or renewals as received transactions. Each RECEIVED entry lists its assets in assets:

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

const history = await wallet.getTransactionHistory()

const deposits = history
  .filter((tx) => tx.type === TxType.TxReceived)
  .flatMap((tx) =>
    (tx.assets ?? [])
      .filter((asset) => asset.assetId === assetId)
      .map(({ amount }) => ({ key: tx.key, createdAt: tx.createdAt, amount })),
  )

The subscription stops when your process stops. After a restart, read the transaction history again to find deposits that arrived while you were offline.

For Issuers

For Integrators

Setup

List Asset Outputs

Credit Deposits

Next Steps

Verify Metadata

Payment History

​Setup

​List Asset Outputs

​Subscribe to New Outputs

​Credit Deposits

​Next Steps

Verify Metadata

Payment History

Setup

List Asset Outputs

Subscribe to New Outputs

Credit Deposits

Next Steps