npm package: @openpets/bags-fm
Description: Plugin for Bags.FM API - Create and launch Solana tokens, manage fee sharing configurations, get trade quotes, and claim fees from token positions.
Latest version: 1.0.3

# Bags.FM Pet

OpenPets plugin for the Bags.FM API - a Solana token launch and fee sharing platform.

## Features

- Get trade quotes for token swaps
- Create swap transactions
- Query token analytics (lifetime fees, creators, claim stats)
- Get claimable fee positions for wallets
- Generate claim transactions
- Create and launch new tokens
- Configure fee sharing among multiple claimers

## Setup

### 1. Get API Key

Visit [https://dev.bags.fm](https://dev.bags.fm) to create an account and generate your API key.

### 2. Configure Environment

Add to your `.env` file:

```bash
BAGS_FM_API_KEY=your_api_key_here
```

### 3. Test Connection

```bash
opencode run "test bags-fm connection"
```

## Available Tools

### Core Tools (Always Loaded)

| Tool | Description |
|------|-------------|
| `bags-fm-test-connection` | Test API connection and credentials |
| `bags-fm-get-trade-quote` | Get a swap quote with price impact |
| `bags-fm-create-swap-transaction` | Create a swap transaction from a quote |
| `bags-fm-get-token-lifetime-fees` | Get total fees collected for a token |
| `bags-fm-get-token-launch-creators` | Get token creators/deployers |
| `bags-fm-get-token-claim-stats` | Get claim statistics for a token |
| `bags-fm-get-claimable-positions` | Get claimable fee positions for a wallet |
| `bags-fm-get-claim-transactions` | Generate claim transactions |

### Optional Tool Groups

Enable additional tools by setting environment variables:

```bash
# Token Launch tools
BAGS_FM_LOAD_TOKEN_LAUNCH_TOOLS=true
# - bags-fm-create-token-info
# - bags-fm-create-launch-transaction

# Fee Share tools
BAGS_FM_LOAD_FEE_SHARE_TOOLS=true
# - bags-fm-get-fee-share-wallet-bulk
# - bags-fm-create-fee-share-config

# Partner tools
BAGS_FM_LOAD_PARTNER_TOOLS=true
# - bags-fm-get-partner-stats
```

## Example Queries

```bash
# Get a swap quote
opencode run "get a bags-fm trade quote for swapping 1 SOL to token mint ABC123"

# Get lifetime fees for a token
opencode run "get bags-fm lifetime fees for token mint ABC123"

# Get claimable positions
opencode run "get bags-fm claimable positions for wallet XYZ789"

# Get token creators
opencode run "who are the bags-fm creators for token mint ABC123"
```

## Key Concepts

### Lamports

A lamport is the smallest unit of SOL. 1 SOL = 1,000,000,000 lamports (10^9).

### Basis Points (bps)

Basis points are used for fee sharing percentages. 100 bps = 1%, 10,000 bps = 100%.

### Token Mints

All tokens are identified by their mint public key (Base58 encoded Solana address).

## Rate Limits

The API has a limit of 1,000 requests per hour per user. Monitor the `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers in responses.

## Read-Only Mode

Enable read-only mode to disable write operations:

```bash
pets read-only bags-fm on
```

This filters out tools like `create-swap-transaction`, `create-token-info`, etc.

## Regenerating Tools

If the API spec changes, regenerate the tools:

```bash
cd pets/bags-fm
pets generate-openapi --verbose
```

**Note:** Bags.FM does not expose a public OpenAPI spec URL. The `openapi-spec.json` file was manually created from their documentation at https://docs.bags.fm. If they add new endpoints, update the local spec file and regenerate.

## Documentation

- [Bags.FM API Docs](https://docs.bags.fm)
- [Bags.FM Developer Dashboard](https://dev.bags.fm)
- [OpenPets OpenAPI Generation Guide](../../docs/openapi-generation.md)