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.
        }
    }
}

Go

SDK: branta-go

Wallets should use PrivacyStrict. 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 handle the error and show nothing on not-found — a missing record just means the address was not posted to Branta.

package main

import (
	"context"

	"github.com/BrantaOps/branta-go"
)

func lookup(ctx context.Context, service *branta.BrantaService, input string, isQRCode bool) {
	var (
		result branta.PaymentsResult
		err    error
	)
	if isQRCode {
		result, err = service.GetPaymentsByQRCode(ctx, input, nil)
	} else {
		result, err = service.GetPayments(ctx, input, "", nil)
	}

	if err != nil || len(result.Payments) == 0 {
		// Not found — show nothing. The address may simply not exist in Branta.
		return
	}

	// Render result.Payments (name and logo)
}

func main() {
	service := branta.NewBrantaService(branta.BrantaClientOptions{
		BaseURL: branta.Production,
		Privacy: branta.PrivacyStrict,
	})
	lookup(context.Background(), service, "bitcoin:bc1q...", false)
}

Swift

SDK: branta-swift

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.

import Branta

let service = BrantaService(options: BrantaClientOptions(
    baseURL: .production,
    privacy: .strict
))

func lookup(input: String, isQRCode: Bool) async {
    do {
        let result = isQRCode
            ? try await service.getPaymentsByQRCode(input)
            : try await 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 {
        // 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.

• Make it searchable. Include the stored counterparty name in whatever your history search already indexes, so a user can find a payment by typing the merchant's name instead of recalling an address, invoice, or date. Search stays local — the field is already on the record.

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.

• ZK Unified — on-chain address, Lightning invoice, and Branta params in one BIP-21 URI (the shape BTCPay checkout uses). Pass the full URI to the SDK; do not split it before lookup.

• 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, and that searching history for the counterparty name returns it.

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.