# PLUGy — Create Token

## THE ONLY CORRECT WAY TO CREATE A TOKEN:

```bash
curl -s -X POST https://plugy.fun/api/agents/trade \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "create",
    "tokenMetadata": {
      "name": "TOKEN NAME HERE",
      "symbol": "TICKER",
      "description": "Token description here",
      "file": "https://example.com/image.png",
      "twitter": "https://x.com/yourhandle",
      "telegram": "https://t.me/yourgroup",
      "website": "https://yoursite.com"
    },
    "devBuyAmount": 0
  }'
```

## MANDATORY RULES:

- Endpoint is **`/api/agents/trade`** — NOT `/api/agents/create`
- The field **`"action": "create"`** is required
- Image field is **`"file"`** — NOT `imageUrl`, NOT `image`
- Dev buy field is **`"devBuyAmount"`** — NOT `devBuySol`, NOT `devBuy`
- All token fields go inside **`"tokenMetadata": { ... }`** — NOT flat at root level
- **`file`** accepts an image URL (`https://...`) or base64-encoded image data
- `twitter`, `telegram`, `website` are optional
- `devBuyAmount` is SOL to buy on creation (0 = create only, no buy)

## FIELD REFERENCE:

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `tokenMetadata.name` | YES | string (max 32) | Token name |
| `tokenMetadata.symbol` | YES | string (max 10) | Ticker |
| `tokenMetadata.description` | YES | string | Description |
| `tokenMetadata.file` | YES | string (max 5 MB) | Image URL or base64 |
| `tokenMetadata.twitter` | no | string | Twitter/X URL |
| `tokenMetadata.telegram` | no | string | Telegram URL |
| `tokenMetadata.website` | no | string | Website URL |
| `devBuyAmount` | no | number | SOL to buy on creation (default 0) |
| `mintSecretKey` | no | string | Pre-generated mint secret key — server signs for you (agent API) |
| `mintPublicKey` | no | string | Pre-generated mint address only — server skips mint signing (human API, you sign client-side) |
| `creatorRewards` | no | boolean | `true` = creator-rewards variant, `false` (default) = cashback variant |

## TOKEN TYPE: cashback vs creator-rewards

By default tokens are created as **cashback** (`creatorRewards` omitted or `false`).
Set `"creatorRewards": true` to create a **creator-rewards** token instead.

```bash
# Creator-rewards token:
-d '{ "action": "create", "creatorRewards": true, "tokenMetadata": { ... }, ... }'

# Cashback token (default, no flag needed):
-d '{ "action": "create", "tokenMetadata": { ... }, ... }'
```

## USING A PRE-GENERATED MINT ADDRESS

Two options depending on whether you want the server to handle mint signing:

### Option A — `mintPublicKey` (recommended for human API / non-custodial)

Generate a keypair locally, pass only the **public key** to the API.
The server returns an unsigned-by-mint transaction; you sign it with **both your wallet
AND the mint keypair** before broadcasting.

```js
// Step 1 — generate locally
const { Keypair } = require('@solana/web3.js');
const kp = Keypair.generate();
console.log('Mint address:', kp.publicKey.toBase58());
// Save kp.secretKey — you'll need it for signing
```

```bash
# Step 2 — pass only the public key
curl -s -X POST https://plugy.fun/api/trade \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "publicKey": "YOUR_WALLET",
    "mintPublicKey": "<mint address from step 1>",
    "tokenMetadata": { ... }
  }'
# Response includes mintSignedByServer: false
# You MUST sign with both your wallet AND the mint keypair before submitting
```

### Option B — `mintSecretKey` (agent API / custodial)

Pass the **full secret key** so the server can partial-sign on your behalf.
Use this with `/api/agents/trade` where the server signs and broadcasts for you.

```js
// Step 1 — generate and export secret key
const { Keypair } = require('@solana/web3.js');
const kp = Keypair.generate();
console.log('Mint address:', kp.publicKey.toBase58());
console.log('Secret (base64):', Buffer.from(kp.secretKey).toString('base64'));
```

```bash
# Step 2 — pass secret key to agent API
curl -s -X POST https://plugy.fun/api/agents/trade \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "action": "create",
    "mintSecretKey": "<base64 secret key from step 1>",
    "tokenMetadata": { ... }
  }'
```

`mintSecretKey` accepts **base64** (64-byte) or **bs58** (standard Solana format).
Server reconstructs the keypair, signs the mint account, and `mintAddress` in the
response will match the address you pre-generated.

## AFTER SUCCESS:

Response will contain:
- `mintAddress` — the new token's contract address
- `explorer` — Solscan transaction link
- `metadataUri` — IPFS metadata link

Tell the user: "Token created! View on PumpFun: https://pump.fun/coin/[mintAddress]"

## COMMON MISTAKES TO AVOID:

❌ `POST /api/agents/create` → WRONG endpoint
❌ `"imageUrl": "..."` → WRONG field name, use `"file"`
❌ `"devBuySol": 0.01` → WRONG field name, use `"devBuyAmount"`
❌ Putting `name`, `symbol` at root level → WRONG, must be inside `tokenMetadata`
❌ `"creatorRewards": "true"` → WRONG, must be boolean `true`, not a string
✅ `POST /api/agents/trade` with `"action": "create"` → CORRECT
✅ `"creatorRewards": true` → correct boolean
✅ `"mintPublicKey": "<base58 address>"` → pass address only (human API, you sign mint client-side)
✅ `"mintSecretKey": "<base64>"` → pass secret key (agent API, server signs mint for you)