Wallets

Embed Branta in your wallet so users see who they are paying before they hit send.

This page is for wallet developers integrating Branta into a send flow. Embedding Branta lets your users see counterparty name and logo before broadcast (and again in payment history afterward) turning an address or invoice into a recognizable payee.

Why integrate Branta

• Users see who they are paying before broadcast (counterparty name and logo), not just an address or invoice.

• Eliminates phishing, supply-chain, address-swap, and man-in-the-middle attacks at point of transaction.

• Works across Bitcoin onchain, Lightning (bolt11, bolt12, lnurl, ln address), Ark, and Silent Payments.

• Privacy-preserving — strict mode never sends plain-text onchain addresses to Branta.

• No permission needed — and one network call per scan or paste.

• Reuse the same counterparty name and logo in payment history, so a past payment reads as a recognizable payee, not an address.

How Branta works for wallets

Your wallet hands raw QR text or user-pasted text to the Branta SDK. The SDK calls Branta in strict privacy mode: onchain destinations only resolve when the QR carries branta_id and branta_secret (ZK-encoded), while bolt11, Ark (ark1…), and Silent Payments (sp1… / tsp1…) resolve using hash-ZK — no secret needed. On a hit, render the returned counterparty name and logo before the user confirms send. On a miss or error, show nothing — a missing record just means the destination was never posted to Branta.

See SDK, Environments, and Authentication for deeper reference.

Integrate

JavaScript

SDK: branta-js

Wallets should use strict privacy mode. Two flows are supported:

• QR scan: call getPaymentsByQrCode with the raw QR text. This handles both on-chain (when the QR includes branta_id / branta_secret) and lightning destinations.

• Copy/paste: call getPayments with the pasted text. Plain-text on-chain addresses will not return results in strict mode — they must be ZK-encoded. bolt11, Ark, and Silent Payments work as plain text (hash-ZK — no secret needed).

Always catch errors and show nothing on not-found — a missing record just means the address was not posted to Branta.

import { BrantaServerBaseUrl } from "@branta-ops/branta";
import { BrantaService } from "@branta-ops/branta/v2";

const service = new BrantaService({
  baseUrl: BrantaServerBaseUrl.Production,
  privacy: 'strict',
});

async function lookup(input: string, isQrCode: boolean) {
  try {
    const result = isQrCode
      ? await service.getPaymentsByQrCode(input)
      : await service.getPayments(input);

    if (result.payments.length === 0) {
      // Not found — show nothing. The address may simply not exist in Branta.
      return;
    }

    // Render result.payments (name and logo)
  } catch {
    // Swallow errors — never surface a "not found" or lookup failure to the user.
  }
}

.NET

SDK: branta-dotnet

Wallets should use Strict privacy mode. Two flows are supported:

• QR scan: call GetPaymentsByQrCodeAsync with the raw QR text. This handles both on-chain (when the QR includes branta_id / branta_secret) and lightning destinations.

• Copy/paste: call GetPaymentsAsync with the pasted text. Plain-text on-chain addresses will not return results in strict mode — they must be ZK-encoded. bolt11, Ark, and Silent Payments work as plain text (hash-ZK — no secret needed).

Always catch errors and show nothing on not-found — a missing record just means the address was not posted to Branta.

using Branta.V2.Extensions;
using Branta.V2.Interfaces;

services.ConfigureBrantaServices(new BrantaClientOptions() {
    BaseUrl = BrantaServerBaseUrl.Production,
    Privacy = PrivacyMode.Strict
});

public class Example(IBrantaService brantaService)
{
    public async Task LookupAsync(string input, bool isQrCode)
    {
        try
        {
            var result = isQrCode
                ? await brantaService.GetPaymentsByQrCodeAsync(input)
                : await brantaService.GetPaymentsAsync(input);

            if (result.Payments.Count == 0)
            {
                // Not found — show nothing. The address may simply not exist in Branta.
                return;
            }

            // Render result.Payments (name and logo)
        }
        catch
        {
            // Swallow errors — never surface a "not found" or lookup failure to the user.
        }
    }
}

Python

SDK: branta-python

Wallets should use PrivacyMode.Strict. Two flows are supported:

• QR scan: call get_payments_by_qr_code with the raw QR text. This handles both on-chain (when the QR includes branta_id / branta_secret) and lightning destinations.

• Copy/paste: call get_payments with the pasted text. Plain-text on-chain addresses will not return results in strict mode — they must be ZK-encoded. bolt11, Ark, and Silent Payments work as plain text (hash-ZK — no secret needed).

Always catch errors and show nothing on not-found — a missing record just means the address was not posted to Branta.

from branta.enums import BrantaServerBaseUrl, PrivacyMode
from branta.options import BrantaClientOptions
from branta.v2 import BrantaService

service = BrantaService(BrantaClientOptions(
    base_url=BrantaServerBaseUrl.Production,
    privacy=PrivacyMode.Strict,
))

async def lookup(input: str, is_qr_code: bool) -> None:
    try:
        result = (
            await service.get_payments_by_qr_code(input)
            if is_qr_code
            else await service.get_payments(input)
        )

        if not result.payments:
            # Not found — show nothing. The address may simply not exist in Branta.
            return

        # Render result.payments (name and logo)
    except Exception:
        # Swallow errors — never surface a "not found" or lookup failure to the user.
        pass

Dart

SDK: branta-dart

Wallets should use PrivacyMode.strict. Two flows are supported:

• QR scan: call getPaymentsByQrCodeAsync with the raw QR text. This handles both on-chain (when the QR includes branta_id / branta_secret) and lightning destinations.

• Copy/paste: call getPaymentsAsync with the pasted text. Plain-text on-chain addresses will not return results in strict mode — they must be ZK-encoded. bolt11, Ark, and Silent Payments work as plain text (hash-ZK — no secret needed).

Always catch errors and show nothing on not-found — a missing record just means the address was not posted to Branta.

import 'package:branta/branta.dart';
import 'package:http/http.dart' as http;

final options = BrantaClientOptions(
  baseUrl: BrantaServerBaseUrl.production,
  privacy: PrivacyMode.strict,
);
final brantaClient = BrantaClient(httpClient: http.Client(), defaultOptions: options);
final service = BrantaService(
  client: brantaClient,
  aesEncryption: AesEncryptionService(),
  defaultOptions: options,
);

Future<void> lookup(String input, bool isQrCode) async {
  try {
    final result = isQrCode
        ? await service.getPaymentsByQrCodeAsync(input)
        : await service.getPaymentsAsync(input);

    if (result.payments.isEmpty) {
      // Not found — show nothing. The address may simply not exist in Branta.
      return;
    }

    // Render result.payments (name and logo)
  } catch (_) {
    // Swallow errors — never surface a "not found" or lookup failure to the user.
  }
}

Kotlin

SDK: branta-kotlin

Wallets should use PrivacyMode.Strict. Two flows are supported:

• QR scan: call getPaymentsByQrCode with the raw QR text. This handles both on-chain (when the QR includes branta_id / branta_secret) and lightning destinations.

• Copy/paste: call getPayments with the pasted text. Plain-text on-chain addresses will not return results in strict mode — they must be ZK-encoded. bolt11, Ark, and Silent Payments work as plain text (hash-ZK — no secret needed).

Always catch errors and show nothing on not-found — a missing record just means the address was not posted to Branta.

val service = BrantaService(
    BrantaClientOptions(
        baseUrl = BrantaServerBaseUrl.Production,
        privacy = PrivacyMode.Strict
    )
)

// In a coroutine scope (e.g. viewModelScope):
suspend fun lookup(input: String, isQrCode: Boolean) {
    try {
        val result = if (isQrCode) {
            service.getPaymentsByQrCode(input)
        } else {
            service.getPayments(input)
        }

        if (result.payments.isEmpty()) {
            // Not found — show nothing. The address may simply not exist in Branta.
            return
        }

        // Render result.payments (name and logo)
    } catch (e: Exception) {
        // Swallow errors — never surface a "not found" or lookup failure to the user.
    }
}

Rust

SDK: branta-rust

Wallets should use PrivacyMode::Strict. Two flows are supported:

• QR scan: call get_payments_by_qr_code with the raw QR text. This handles both on-chain (when the QR includes branta_id / branta_secret) and lightning destinations.

• Copy/paste: call get_payments with the pasted text. Plain-text on-chain addresses will not return results in strict mode — they must be ZK-encoded. bolt11, Ark, and Silent Payments work as plain text (hash-ZK — no secret needed).

Always handle the Result and show nothing on not-found — a missing record just means the address was not posted to Branta.

use branta::{BrantaClientOptions, BrantaServerBaseUrl, BrantaService, PrivacyMode};

let service = BrantaService::new(BrantaClientOptions {
    base_url: BrantaServerBaseUrl::Production,
    privacy: PrivacyMode::Strict,
    default_api_key: None,
    hmac_secret: None,
});

async fn lookup(service: &BrantaService, input: &str, is_qr_code: bool) {
    let result = if is_qr_code {
        service.get_payments_by_qr_code(input, None).await
    } else {
        service.get_payments(input, None, None).await
    };

    match result {
        Ok(result) if result.payments.is_empty() => {
            // Not found — show nothing. The address may simply not exist in Branta.
        }
        Ok(result) => {
            // Render result.payments (name and logo)
        }
        Err(_) => {
            // Swallow errors — never surface a "not found" or lookup failure to the user.
        }
    }
}

Payment history

Once a payment resolves to a counterparty, render the counterparty name and logo in your transaction history, too.

This is recommended for all wallet integrations:

• Persist at send time. When the send-flow lookup returns a hit, store the counterparty name and logo on your transaction record. History rendering is then a local read — no extra network calls, and it works offline.

Test your integration

Scan the example QR codes with your wallet to confirm each scenario renders the right thing before broadcast:

• On-chain and Lightning — counterparty name and logo render.

• ZK On-chain and ZK Lightning — encrypted destinations resolve via branta_id / branta_secret.

• Not found — your wallet shows nothing (a miss is not an error).

• Payment history — after paying a resolved QR, confirm the counterparty name and logo still render on the history row.

Each variant is published for both Production and Staging — match the environment your SDK is pointed at.

Wallets using Branta

See the live list at branta.pro/network.

To be listed, open a PR on branta-network.