TypeScript SDK

The official Bag SDK for TypeScript and JavaScript. It wraps the Bag REST API with typed methods, error handling, and a clean interface.

npm install @getbagsapp/sdk

Setup

import { Bag } from "@getbagsapp/sdk";

const bag = new Bag({
  apiKey: process.env.BAG_API_KEY!,
});

Configuration

Option	Type	Required	Default	Description
`apiKey`	`string`	Yes	—	Your Bag API key (`bag_test_sk_` or `bag_live_sk_`)
`baseUrl`	`string`	No	`https://justusebag.xyz`	API base URL (override for self-hosted or local dev)

Payment Links

Create a payment link

const link = await bag.paymentLinks.create({
  name: "Pro Plan",
  amount: 29.99,
  network: "base_sepolia",
});

Parameters:

Field	Type	Required	Description
`name`	`string`	Yes	Display name
`amount`	`number`	Yes	Price in USD
`network`	`Network`	Yes	Blockchain network
`description`	`string`	No	Description shown on checkout
`currency`	`string`	No	Defaults to `USD`
`token`	`string`	No	Defaults to `USDC`
`networks`	`Network[]`	No	Multiple chains
`merchantWalletAddress`	`string`	No	Override receiving wallet
`merchantWalletAddresses`	`Record<string, string>`	No	Per-network wallets

List payment links

const links = await bag.paymentLinks.list();

Get a payment link

const link = await bag.paymentLinks.get("665f1a2b3c4d5e6f7a8b9c0d");

Update a payment link

const updated = await bag.paymentLinks.update("665f1a2b3c4d5e6f7a8b9c0d", {
  amount: 39.99,
  active: false,
});

Delete a payment link

await bag.paymentLinks.delete("665f1a2b3c4d5e6f7a8b9c0d");

Transactions

List transactions

const transactions = await bag.transactions.list();

Create a transaction

const tx = await bag.transactions.create({
  amount: 29.99,
  token: "USDC",
  network: "base_sepolia",
  txHash: "0xabc123...",
  walletAddress: "0xCustomerWallet",
  customerEmail: "customer@example.com",
  paymentLinkId: "665f1a2b3c4d5e6f7a8b9c0d",
});

Parameters:

Field	Type	Required	Description
`amount`	`number`	Yes	Payment amount
`token`	`string`	Yes	Token (e.g. `USDC`)
`network`	`Network`	Yes	Blockchain network
`txHash`	`string`	Yes	On-chain transaction hash
`walletAddress`	`string`	Yes	Customer's wallet address
`customerEmail`	`string`	No	Customer email
`customerName`	`string`	No	Customer name
`customerAddress`	`string`	No	Customer address
`paymentLinkId`	`string`	No	Associated payment link

Checkout

Get a tax quote

const quote = await bag.checkout.getTaxQuote({
  paymentLinkId: "665f1a2b3c4d5e6f7a8b9c0d",
  customerAddress: {
    address_line_1: "100 Main St",
    address_city: "San Francisco",
    address_province: "CA",
    address_postal_code: "94105",
    address_country: "US",
  },
});

Returns: { subtotalCents, taxCents, totalCents, calculationId, quoteToken }

Create a checkout session

const session = await bag.checkout.createSession({
  linkId: "665f1a2b3c4d5e6f7a8b9c0d",
  quoteToken: quote.quoteToken,
  walletAddress: "0xCustomerWallet",
  walletType: "evm",
  network: "base_sepolia",
  customer: {
    name: "Jane Doe",
    email: "jane@example.com",
    address: "100 Main St, San Francisco, CA 94105",
    country: "US",
  },
  totalsSnapshot: {
    subtotalCents: quote.subtotalCents,
    taxCents: quote.taxCents,
    totalCents: quote.totalCents,
    calculationId: quote.calculationId,
  },
});

Get a checkout session

const status = await bag.checkout.getSession("session-uuid");

Submit a transaction hash

await bag.checkout.submit("session-uuid", "0xabc123...");

Error handling

The SDK throws BagError for API errors:

import { Bag, BagError } from "@getbagsapp/sdk";

try {
  await bag.paymentLinks.create({ name: "Test", amount: 0, network: "base" });
} catch (error) {
  if (error instanceof BagError) {
    console.error(`${error.statusCode}: ${error.message}`);
    console.error(`Code: ${error.code}`);
  }
}

Property	Type	Description
`statusCode`	`number`	HTTP status code
`message`	`string`	Error message
`code`	`string \| undefined`	Machine-readable error code

Types

Network

type Network =
  | "base" | "ethereum" | "polygon" | "solana"
  | "base_sepolia" | "eth_sepolia" | "solana_devnet";

TransactionStatus

type TransactionStatus =
  | "broadcasted" | "pending" | "confirming"
  | "completed" | "failed" | "refunded";

ApiResponse

interface ApiResponse<T> {
  status: "success" | "error";
  data?: T;
  message?: string;
  code?: string;
  hint?: string;
}

What's next

Create a Payment Link

Use the SDK to create your first payment link.

Build a Custom Checkout

Use the checkout methods for a custom payment flow.

API Reference

Full REST API documentation.

TypeScript SDK

Create a Payment Link

Build a Custom Checkout

API Reference

On this page