MBGA

Reactive primitives for Spark apps.

Features

• Wallet Connection — connect/disconnect with multiple wallet connectors (Sats Connect, Spark SDK)
• Balance Queries — fetch wallet balances with automatic caching
• Payments — send payments, create invoices, estimate fees, and wait for payment confirmations
• Message Signing — sign messages with connected wallets
• Flashnet Auth — API-key authentication for Flashnet orchestration (swaps, cross-chain)
• React Hooks — first-class React bindings powered by TanStack Query
• TypeScript — fully typed APIs with strict mode
• SSR Ready — compatible with server-side rendering frameworks
• Tiny Bundle — tree-shakeable, minimal footprint

Quick Start

1. Install

pnpm add mbga @mbga/connectors @tanstack/react-query

2. Configure

import { createConfig, sparkMainnet } from 'mbga'
import { xverse } from 'mbga/connectors'

export const config = createConfig({
  network: sparkMainnet,
  connectors: [xverse()],
})

3. Use

import { MbgaProvider, useBalance, useConnect, useConnection, useDisconnect } from 'mbga'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { config } from './config'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MbgaProvider config={config}>
        <Wallet />
      </MbgaProvider>
    </QueryClientProvider>
  )
}

function Wallet() {
  const { connect } = useConnect()
  const { disconnect } = useDisconnect()
  const connection = useConnection()
  const { data: balance } = useBalance()

  if (connection.status === 'connected') {
    return (
      <div>
        <p>{connection.address}</p>
        <p>{balance?.balanceSat.toString()} sats</p>
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    )
  }

  return <button onClick={() => connect()}>Connect Wallet</button>
}

Scaffold a new project

pnpm create mbga

Packages

Package	Description
mbga	React Hooks for Spark
@mbga/core	VanillaJS library for Spark
@mbga/connectors	Collection of wallet connectors for MBGA
@mbga/kit	Pre-built React UI components for wallet connection
@mbga/test	Test utilities for MBGA
@mbga/flashnet	Flashnet authentication and orchestration
create-mbga	Scaffold a new MBGA project

Community

• GitHub Discussions — ask questions and share ideas

Contributing

Contributions are welcome! Please read the Contributing Guide before submitting a pull request.

Acknowledgments

MBGA's architecture is heavily inspired by these projects — thank you to the teams behind them:

• wagmi by wevm — the React hooks pattern, connector interface, config/provider design, and overall developer experience that MBGA is modeled after
• ConnectKit by Family — the @mbga/kit UI components (ConnectButton, ConnectModal, AccountModal, theming) draw from ConnectKit's design patterns
• viem by wevm — documentation site structure and tooling

License

Apache-2.0