# PLUGy — Fee Sharing (PumpFun Creator Fees)

## POST /api/agents/fee-sharing

Manage how your token's trading fees are distributed. After launching a token on pump.fun, the creator can configure who receives what percentage of trading fees.

**Auth:** `x-api-key: plugy_...` header required.

**Program:** `pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ`

---

## HOW FEE SHARING WORKS

1. **Create** — call `createFeeSharing` once per token. You become admin and sole shareholder (100%).
2. **Update** — call `updateFeeShares` to split fees across multiple wallets.
3. **Distribute** — call `distributeFees` to send accumulated BC vault fees to all shareholders. This is **permissionless** — anyone can trigger it.
4. **Lock** (optional) — call `revokeFeeSharing` to permanently freeze the config. Irreversible.
5. **Transfer** (optional) — call `transferFeeSharingAuthority` to hand admin to another wallet.
6. **Reset** (optional) — call `resetFeeSharing` to wipe shareholders and assign a new admin.

**Important:** After `createFeeSharing`, creator fees for that token are routed to a new vault (seeded by the sharing config, not the creator wallet). The `collectCreatorFee` (trade endpoint) still works for your **other** tokens, but **will not include** fees from fee-sharing-enabled tokens. Use `distributeFees` to collect fees from fee-sharing tokens instead.

Shares are expressed in **basis points** (bps). 1 bps = 0.01%. All shareholders must sum to exactly **10000 bps** (100%).

---

## CREATE FEE SHARING

Create the fee sharing config for a token you launched. You become admin and 100% shareholder.

```bash
curl -s -X POST https://plugy.fun/api/agents/fee-sharing \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "createFeeSharing",
    "mint": "TOKEN_MINT_ADDRESS"
  }'
```

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `action` | `"createFeeSharing"` | Yes | — | Must be `"createFeeSharing"` |
| `mint` | string | Yes | — | Token mint address |
| `priorityFee` | number | No | `0.0001` | Priority fee in SOL |

Response:
```json
{
  "success": true,
  "txSignature": "5abc...xyz",
  "explorer": "https://solscan.io/tx/5abc...xyz",
  "action": "createFeeSharing",
  "mint": "TOKEN_MINT_ADDRESS"
}
```

---

## UPDATE FEE SHARES

Split fees across multiple wallets. All `shareBps` values must sum to exactly 10000.

```bash
curl -s -X POST https://plugy.fun/api/agents/fee-sharing \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "updateFeeShares",
    "mint": "TOKEN_MINT_ADDRESS",
    "shareholders": [
      { "address": "Wallet1PublicKey", "shareBps": 6000 },
      { "address": "Wallet2PublicKey", "shareBps": 4000 }
    ]
  }'
```

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `action` | `"updateFeeShares"` | Yes | — | Must be `"updateFeeShares"` |
| `mint` | string | Yes | — | Token mint address |
| `shareholders` | array | Yes | — | Array of `{ address, shareBps }` |
| `priorityFee` | number | No | `0.0001` | Priority fee in SOL |

**Important:** Distribute all pending fees BEFORE updating shares. Otherwise new shareholders receive fees they didn't earn.

Response:
```json
{
  "success": true,
  "txSignature": "5abc...xyz",
  "explorer": "https://solscan.io/tx/5abc...xyz",
  "action": "updateFeeShares",
  "mint": "TOKEN_MINT_ADDRESS",
  "shareholders": [
    { "address": "Wallet1PublicKey", "shareBps": 6000 },
    { "address": "Wallet2PublicKey", "shareBps": 4000 }
  ]
}
```

---

## DISTRIBUTE FEES

Send accumulated creator fees from the bonding curve vault to all shareholders. This is **permissionless** — any wallet can trigger it, not just the admin.

```bash
curl -s -X POST https://plugy.fun/api/agents/fee-sharing \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "distributeFees",
    "mint": "TOKEN_MINT_ADDRESS"
  }'
```

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `action` | `"distributeFees"` | Yes | — | Must be `"distributeFees"` |
| `mint` | string | Yes | — | Token mint address |
| `priorityFee` | number | No | `0.0001` | Priority fee in SOL |

Response:
```json
{
  "success": true,
  "txSignature": "5abc...xyz",
  "explorer": "https://solscan.io/tx/5abc...xyz",
  "action": "distributeFees",
  "mint": "TOKEN_MINT_ADDRESS",
  "pendingBcSol": 0.123456,
  "numShareholders": 3
}
```

**Note:** This distributes only from the **bonding curve vault** (native SOL from pre-migration trading). AMM vault fees (WSOL from PumpSwap) are distributed automatically when `updateFeeShares` is called.

---

## REVOKE FEE SHARING

⚠️ **PERMANENTLY** lock the fee sharing config. No further changes to shareholders, shares, or admin will be possible. **This is IRREVERSIBLE.**

```bash
curl -s -X POST https://plugy.fun/api/agents/fee-sharing \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "revokeFeeSharing",
    "mint": "TOKEN_MINT_ADDRESS"
  }'
```

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `action` | `"revokeFeeSharing"` | Yes | — | Must be `"revokeFeeSharing"` |
| `mint` | string | Yes | — | Token mint address |
| `priorityFee` | number | No | `0.0001` | Priority fee in SOL |

---

## TRANSFER FEE SHARING AUTHORITY

Transfer the admin role to another wallet. The new admin can then update shareholders, revoke, or reset.

```bash
curl -s -X POST https://plugy.fun/api/agents/fee-sharing \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "transferFeeSharingAuthority",
    "mint": "TOKEN_MINT_ADDRESS",
    "newAdmin": "NEW_ADMIN_WALLET"
  }'
```

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `action` | `"transferFeeSharingAuthority"` | Yes | — | Must be `"transferFeeSharingAuthority"` |
| `mint` | string | Yes | — | Token mint address |
| `newAdmin` | string | Yes | — | New admin wallet address (base58) |
| `priorityFee` | number | No | `0.0001` | Priority fee in SOL |

---

## RESET FEE SHARING

Wipe all shareholders and set a new admin. **Distribute all pending fees BEFORE resetting — undistributed fees will be lost.**

```bash
curl -s -X POST https://plugy.fun/api/agents/fee-sharing \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "resetFeeSharing",
    "mint": "TOKEN_MINT_ADDRESS",
    "newAdmin": "NEW_ADMIN_WALLET"
  }'
```

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `action` | `"resetFeeSharing"` | Yes | — | Must be `"resetFeeSharing"` |
| `mint` | string | Yes | — | Token mint address |
| `newAdmin` | string | Yes | — | New admin wallet address (base58) |
| `priorityFee` | number | No | `0.0001` | Priority fee in SOL |

---

## GET FEE SHARING CONFIG

Read the current fee sharing configuration for a token. No transaction — read-only.

```bash
curl -s -X POST https://plugy.fun/api/agents/fee-sharing \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "getFeeSharingConfig",
    "mint": "TOKEN_MINT_ADDRESS"
  }'
```

Response:
```json
{
  "success": true,
  "action": "getFeeSharingConfig",
  "exists": true,
  "status": "Active",
  "mint": "TOKEN_MINT_ADDRESS",
  "admin": "AdminWalletAddress",
  "adminRevoked": false,
  "shareholders": [
    { "address": "Wallet1PublicKey", "shareBps": 6000 },
    { "address": "Wallet2PublicKey", "shareBps": 4000 }
  ]
}
```

If no config exists yet:
```json
{
  "success": true,
  "action": "getFeeSharingConfig",
  "exists": false,
  "message": "No fee sharing config found for this mint. Use createFeeSharing to create one."
}
```

---

## UNSIGNED TX ENDPOINT (HUMAN WALLETS)

If you're building a UI or need **unsigned transactions** instead of custodial execution:

**POST /api/fee-sharing** — same actions, same parameters, but requires a `publicKey` field and returns an unsigned base64 transaction instead of executing it.

```bash
curl -s -X POST https://plugy.fun/api/fee-sharing \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "YOUR_WALLET_ADDRESS",
    "action": "createFeeSharing",
    "mint": "TOKEN_MINT_ADDRESS"
  }'
```

Response:
```json
{
  "success": true,
  "action": "createFeeSharing",
  "transaction": "base64EncodedTransaction..."
}
```

Sign and submit the transaction using your wallet (Phantom, Solflare, etc.).

---

## ERROR HANDLING

If the API returns an error, show the **exact error message** to the user. Do NOT paraphrase.

Common errors:
- `"No fee sharing config found"` — call `createFeeSharing` first
- `"Admin is revoked"` — config was permanently locked, cannot modify
- `"Not authorized"` — caller is not the admin
- `"Agent wallet has no SOL"` — fund the wallet first

---

## COMMON MISTAKES

❌ Calling `updateFeeShares` without distributing pending fees first → shareholders get wrong amounts
❌ Calling `revokeFeeSharing` by accident → **IRREVERSIBLE**, config is permanently locked
❌ Shareholders summing to less or more than 10000 bps → will fail
❌ Using `createFeeSharing` on a token you didn't create → will fail (only the creator can)
❌ Expecting `collectCreatorFee` to include fee-sharing tokens → it won't (use `distributeFees` for those)
✅ `createFeeSharing` → then `updateFeeShares` → then `distributeFees` → CORRECT
✅ Always distribute fees before updating shareholders → CORRECT
✅ Anyone can call `distributeFees` — shareholders don't need to claim individually