bags-buy-button

bags-buy-button is a reusable, open-source React component that lets any website embed a “Buy” button for a Bags.fm token.
Clicking the button opens a modal with live token analytics from the Bags.fm API and a wallet-native buy flow powered by Solana.

The goal is to turn your visitors into token holders without sending them to an external exchange.

Features

• Drop-in Buy button: <BuyButton contractAddress="TOKEN_CA" apiKey="BAGS_API_KEY" />
• Token analytics: Name, symbol, market cap, volume, traders, lifetime royalties
• Mini price chart: Sparkline-style chart rendered with Chart.js
• Wallet-native flow: Detects Phantom in-browser and pushes a transaction for signing
• Modern UI: TailwindCSS, responsive, mobile-friendly, and accessible
• Hackathon ready: Built for Bags Hackathon projects and AI SaaS tools

Tech stack

• Frontend: React, TypeScript, Vite, TailwindCSS, Axios, Chart.js
• Blockchain: @solana/web3.js, Phantom via window.solana
• Build: Vite library mode + type generation via vite-plugin-dts
• Tests: Jest + ts-jest

Installation

npm install bags-buy-button

If you are working locally with this repo:

git clone <your-fork-or-repo-url>
cd bags-buy-button
npm install
npm run dev

Vite will start a dev server and open the demo app that lives in demo/.

Basic usage (React)

import React from "react";
import { BuyButton } from "bags-buy-button";
import "bags-buy-button/dist/style.css"; // if you decide to ship styles separately

export const Page = () => {
  return (
    <div>
      <h1>Have a slice of my Bags token</h1>
      <BuyButton
        contractAddress="YOUR_BAGS_TOKEN_MINT"
        apiKey="YOUR_BAGS_API_KEY"
        buttonText="Have a Slice"
        theme="dark"
      />
    </div>
  );
};

Props

• contractAddress (string, required): Solana mint address of your Bags.fm token.
• apiKey (string, required): Bags.fm API key.
• buttonText (string, optional): Custom label for the button. Default: "Have a Slice".
• theme ("light" | "dark", optional): Modal/button theme. Default: "dark".
• color (string, optional): Custom button background color (CSS color string).
• size ("sm" | "md" | "lg", optional): Button size. Default: "md".

Vanilla JS usage

This package is primarily built for React, but you can still use it in a non-React setup by:

1. Bundling React + this library into your site (e.g. via Vite, Webpack, or a micro-frontend).
2. Rendering into a DOM node from a small bootstrap script.

Example with a simple script entry:

// main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { BuyButton } from "bags-buy-button";
import "bags-buy-button/dist/style.css";

const mountNode = document.getElementById("bags-buy-button");

if (mountNode) {
  ReactDOM.createRoot(mountNode).render(
    <React.StrictMode>
      <BuyButton
        contractAddress="YOUR_BAGS_TOKEN_MINT"
        apiKey="YOUR_BAGS_API_KEY"
      />
    </React.StrictMode>
  );
}

In your HTML:

<div id="bags-buy-button"></div>
<script type="module" src="/main.tsx"></script>

Wallet setup

• Supported wallets: Phantom (via window.solana). Solflare and additional wallets can be wired in via the Solana Wallet Adapter ecosystem.
• Detection: The library looks for window.solana with isPhantom === true.
• Flow:
  • If Phantom is not detected, the modal shows: “Install Phantom Wallet to continue.”
  • If detected, the user can connect and sign a demo transaction prepared via @solana/web3.js.

No private keys are ever handled by this library. All transactions are created on the client and signed by the user in their wallet.

Bags.fm API usage

The hook useTokenData calls the Bags.fm API to fetch token analytics.

Default base URL (you can adjust it in src/hooks/useTokenData.ts if the Bags API changes):

• https://api.bags.fm/v1/tokens/:contractAddress/stats

Headers:

• x-api-key: YOUR_BAGS_API_KEY

Shape (approximate – the hook maps flexible field names):

• name / metadata.name
• symbol / metadata.symbol
• marketCap or market_cap
• volume24h or volume_24h
• traderCount or traders
• lifetimeRoyalties or royalties
• price / current_price
• priceChange24h / price_change_24h
• priceHistory[] with { time, value }

Development

Clone and run the demo:

git clone <your-fork-or-repo-url>
cd bags-buy-button
npm install
npm run dev

This will:

• Start Vite in dev mode.
• Serve index.html, which mounts the demo app in demo/.
• Render an example SaaS landing page with the BuyButton wired up.

Run tests:

npm test

Build the library:

npm run build

The compiled artifacts (ESM + CJS + types) will be emitted to dist/.

NPM publishing

This project is preconfigured to be published to your own npm account.

npm login
npm version patch   # or minor / major
npm publish

Key package.json fields:

{
  "name": "bags-buy-button",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/index.es.js",
  "types": "dist/index.d.ts",
  "license": "MIT"
}

Security notes

• No private keys are ever stored or handled by this package.
• All Solana transactions are created on the client and must be signed in the user’s wallet.
• For production, you should:
  • Use a dedicated RPC provider.
  • Plug in Jupiter’s swap API to replace the demo transaction generation.
  • Add rate limiting and monitoring around your Bags.fm API key.

Hackathon notes

This package is designed for the Bags Hackathon:

• Bags API integration: useTokenData pulls token analytics from Bags.fm.
• Token analytics UI: BuyModal, TokenStats, and PriceChart provide a clean card layout.
• Wallet integration: Phantom detection via window.solana and a demo Solana transaction flow.
• Token purchase flow: The structure is in place to plug in Jupiter routing for SOL → token swaps.

Fork it, wire in your actual token and Bags API key, and drop the BuyButton into your project.

License

MIT © 2026