Blacklist

The blacklist lets an issuer restrict which wallets may move a specific asset. Each record targets a single (asset, wallet) pair: a wallet blacklisted for asset A can still transact any other asset. Enforcement happens at transfer time and applies to the wallet whether it is the sender or the recipient of the asset.

This is an issuer-only capability. You can only manage the blacklist for assets you issued

Lifecycle

How it works

When you add a wallet to an asset's blacklist, a record is created with the following shape:

Transfer enforcement

The blacklist record itself only stores the restriction — the block is applied by the spend/transfer layer. On every transfer of the asset, both endpoints of the transfer are checked:

• If the sender wallet is blacklisted for the asset, the transfer fails.
• If the recipient wallet is blacklisted for the asset, the transfer fails.

Because both sides are checked independently, clearing only one side is not enough. If both the sender and the recipient are blacklisted, you must remove both records before transfers resume.

Endpoints

All calls go through the broadcastRequest helper from the Authentication guide.

Add a wallet to the blacklist

import { AmpActions } from '@blockstream/amp-registry';

const result = await broadcastRequest<typeof AmpActions.addToBlacklist>({
  action: 'add',
  resource: `/amp/assets/${assetId}/wallet/${walletId}/blacklist`,
});

if (result.status !== 'success') {
  throw new Error(`Add to blacklist failed: ${result.message}`);
}

Adding the same (asset, wallet) pair twice fails with WalletAlreadyInBlacklistForAsset (see Errors).

Get a single record

Fetch one record by its (asset, wallet) pair:

const record = await broadcastRequest<typeof AmpActions.getBlacklistRecord>({
  action: 'get',
  resource: `/amp/assets/${assetId}/wallet/${walletId}/blacklist`,
});

// record.details.asset_id  === assetId
// record.details.wallet_id === walletId

List a wallet's blacklist

Return every asset a given wallet is blacklisted for. Supports a filters object; pass an empty object to list everything.

const walletBlacklist = await broadcastRequest<typeof AmpActions.listWalletBlacklist>({
  action: 'get',
  resource: `/amp/assets/wallet/${walletId}/blacklist`,
  details: { filters: {} },
});

// walletBlacklist.details         -> array of asset ids
// walletBlacklist.metadata.total_count -> number of matching records

List an asset's blacklist

Return every wallet blacklisted for a given asset. Use the optional wallet_ids filter to narrow the result to specific wallets.

// All blacklisted wallets for the asset
const all = await broadcastRequest<typeof AmpActions.listAssetBlacklist>({
  action: 'get',
  resource: `/amp/assets/${assetId}/blacklist`,
  details: { filters: {} },
});
// all.details -> array of wallet ids

// Only the records matching the given wallet ids
const filtered = await broadcastRequest<typeof AmpActions.listAssetBlacklist>({
  action: 'get',
  resource: `/amp/assets/${assetId}/blacklist`,
  details: { filters: { wallet_ids: [walletId] } },
});

Remove from the blacklist

const removed = await broadcastRequest<typeof AmpActions.removeFromBlacklist>({
  action: 'delete',
  resource: `/amp/assets/${assetId}/wallet/${walletId}/blacklist`,
});

if (removed.status !== 'success') {
  throw new Error(`Remove from blacklist failed: ${removed.message}`);
}

After removal, the wallet can send and receive the asset again. Allow the wallet state to settle (wait for the unlocked balance) before issuing the next transfer.

Errors

Notes

• Per-pair scope. Restrictions are keyed on (asset_id, wallet_id). Blacklisting a wallet for one asset has no effect on its other assets.
• Both directions blocked. A blacklisted wallet cannot send or receive the asset. Removing only the sender's record still leaves the transfer blocked if the recipient is blacklisted, and vice versa.
• Issuer-scoped. Only the issuer of an asset can create, list, or remove its blacklist records.

Next steps

• Managing Restrictions: other transfer restriction types
• Sending Assets: how transfers are submitted and validated
• Monitoring: tracking asset state and balances