@branta-ops/branta

JavaScript SDK for Branta. ESM only.

Use verify() on send and addPayment() on receive. Status handling and parent platforms are in the developer docs.

Install

npm i @branta-ops/branta

Send

import { BrantaEnvironment, BrantaService } from "@branta-ops/branta";

const service = new BrantaService({
  environment: BrantaEnvironment.Production, // Staging everywhere else
});

const result = await service.verify(input); // scanned QR or pasted text

switch (result.status) {
  case "match":
    // Show the card for result.payments[0]. Link it to result.verifyUrl.
    // What to send is result.matchedDestinations — each has type + plaintext value.
    // e.g. usdt_polygon / usdc_polygon / bitcoin_address / bolt11. Do not infer token from pol:.
    break;
  case "unknown":
    // Not in Branta — show nothing.
    break;
  case "tampered":
    // Destination was altered. Warn. Do not show a verified card.
    break;
  case "incomplete":
    // 5xx, 429, or unreachable. Tell the user. Do not treat as unknown.
    break;
}

On-chain Bitcoin needs a bitcoin: URI with branta_id / branta_secret. Polygon EVM rails (usdt_polygon, usdc_polygon) need a pol: URI with the same params — token is on matchedDestinations[].type, not the pol: scheme. bolt11, Ark, and silent payments resolve from the value. A bare address (including bare 0x) is unknown.

Missing crypto throws crypto_unavailable. Do not treat that as unknown. A 404 is unknown. 5xx, 429, no network, or a 30s HTTP timeout is incomplete.

Receive

import {
  BrantaEnvironment,
  BrantaService,
  DestinationType,
  PaymentBuilder,
} from "@branta-ops/branta";

const service = new BrantaService({
  environment: BrantaEnvironment.Production,
  apiKey: "<api-key>",
});

const payment = new PaymentBuilder()
  .setDescription("Invoice #12345")
  .addDestination("bc1q…", DestinationType.BitcoinAddress)
  .setTtl(600) // seconds
  .build();

const { secret, verifyUrl } = await service.addPayment(payment);

Store secret with the invoice. Put branta_id and branta_secret on the invoice QR.

Crypto

Browsers on HTTPS: nothing to do.

Browsers on HTTP, or React Native / Expo: pass crypto, and use service.createPaymentBuilder() instead of new PaymentBuilder().

React Native / Expo — @noble:

npm i @noble/hashes @noble/ciphers

import { BrantaEnvironment, BrantaService, createNobleCryptoProvider } from "@branta-ops/branta";
import { sha256 } from "@noble/hashes/sha2.js";
import { hmac } from "@noble/hashes/hmac.js";
import { gcm } from "@noble/ciphers/aes.js";
import { randomBytes } from "@noble/hashes/utils.js";

const service = new BrantaService({
  environment: BrantaEnvironment.Production,
  crypto: createNobleCryptoProvider({ sha256, hmac, gcm, randomBytes }),
});

Browser on HTTP — @peculiar/webcrypto:

npm i @peculiar/webcrypto

import { Crypto } from "@peculiar/webcrypto";
import { BrantaEnvironment, BrantaService } from "@branta-ops/branta";

const service = new BrantaService({
  environment: BrantaEnvironment.Production,
  crypto: new Crypto(),
});

Changelog · Security