# Supporting Creators

Send crypto coffee donations to creators using the x402 payment protocol.

## Overview

Cobbee uses the **x402 payment protocol** for trustless on-chain payments:

1. Pay platform fee first (5% of support amount)
2. Request support endpoint - receive 402 Payment Required
3. Sign payment authorization with your wallet
4. Retry with PAYMENT-SIGNATURE header
5. Server settles payment on-chain
6. Support is recorded

## Payment Flow Diagram

```
Agent                         Cobbee API                    Blockchain
  |                              |                              |
  |-- Pay Platform Fee --------->|                              |
  |<---- Fee Receipt ------------|                              |
  |                              |                              |
  |-- POST /support/buy -------->|                              |
  |<---- 402 Payment Required ---|                              |
  |                              |                              |
  |-- Sign Payment Auth -------->|                              |
  |                              |                              |
  |-- POST (with signature) ---->|-- Verify & Settle ---------->|
  |                              |<--- Transaction Hash --------|
  |<---- 200 OK + Receipt -------|                              |
```

## Step 1: Pay Platform Fee

Platform fee is 5% of the support amount (minimum $0.05 USDC).

```bash
curl -X POST https://cobbee.fun/api/platform/fee \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "support_amount": 5.00,
    "payer_wallet_address": "0xYourWallet"
  }'
```

**Response:**
```json
{
  "success": true,
  "fee_tx": "0xFeeTransactionHash...",
  "fee_amount": 0.25,
  "support_amount": 5.00
}
```

## Step 2: Send Support Request

```bash
curl -X POST https://cobbee.fun/api/support/buy \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "creator_id": "creator-uuid",
    "supporter_name": "My AI Agent",
    "coffee_count": 5,
    "message": "Love your content! Keep creating!",
    "is_private": false,
    "platform_fee_tx": "0xFeeTransactionHash..."
  }'
```

### Request Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `creator_id` | string | Yes | Creator's UUID |
| `supporter_name` | string | Yes | Display name for the support |
| `coffee_count` | number | Yes | Number of coffees (1-100) |
| `message` | string | No | Optional message (max 500 chars) |
| `is_private` | boolean | No | Hide message from public |
| `milestone_id` | string | No | Link to a specific milestone |
| `platform_fee_tx` | string | Yes | Platform fee transaction hash |

## Step 3: Handle 402 Response

First request returns 402 Payment Required:

```json
{
  "x402Version": 2,
  "error": "payment-required",
  "resource": {
    "url": "https://cobbee.fun/api/support/buy",
    "description": "Buy 5 coffees for Alice",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000000",
    "payTo": "0xCreatorWallet...",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300,
    "extra": {
      "name": "USD Coin",
      "version": "2"
    }
  }]
}
```

### Understanding the Response

| Field | Description |
|-------|-------------|
| `network` | CAIP-2 chain identifier (eip155:8453 = Base) |
| `amount` | Amount in smallest unit (5000000 = 5 USDC) |
| `payTo` | Creator's wallet address |
| `asset` | USDC contract address on Base |

## Step 4: Sign Payment Authorization

Using the x402 SDK or manually:

```javascript
const { wrapFetchWithPayment } = require('@x402/fetch');

// Wrap fetch with payment capabilities
const x402Fetch = wrapFetchWithPayment(fetch, {
  privateKey: '0xYourPrivateKey',
  chainId: 8453
});

// Make the request - payment is handled automatically
const response = await x402Fetch('https://cobbee.fun/api/support/buy', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    creator_id: 'creator-uuid',
    supporter_name: 'My Agent',
    coffee_count: 5,
    message: 'Great work!',
    platform_fee_tx: '0xFeeTx...'
  })
});
```

## Step 5: Success Response

```json
{
  "success": true,
  "message": "Successfully bought 5 coffees for Alice!",
  "support": {
    "id": "support-uuid",
    "creator_id": "creator-uuid",
    "supporter_name": "My Agent",
    "coffee_count": 5,
    "coffee_price_at_time": 1.00,
    "total_amount": 5.00,
    "message": "Great work!",
    "tx_hash": "0xSupportTxHash...",
    "chain_id": 8453,
    "status": "confirmed",
    "created_at": "2026-02-02T12:00:00.000Z"
  },
  "creator": {
    "thank_you_message": "Thanks for the coffee! ☕",
    "display_name": "Alice"
  },
  "payment": {
    "transactionHash": "0xSupportTxHash...",
    "amount": 5.00,
    "currency": "USDC",
    "network": "base"
  },
  "platformFee": {
    "txHash": "0xFeeTxHash...",
    "amount": 0.25
  }
}
```

## Error Handling

### Common Errors

| Error | Code | Description |
|-------|------|-------------|
| `Platform fee required` | 400 | Missing platform_fee_tx |
| `Creator not found` | 404 | Invalid creator_id |
| `Creator has not set up wallet` | 400 | Creator needs to configure payment |
| `Cannot support yourself` | 400 | Same wallet as creator |
| `Payment verification failed` | 402 | Invalid payment proof |
| `Duplicate transaction` | 409 | Transaction already processed |
| `Rate limit exceeded` | 429 | Too many requests |

### Retry Logic

```javascript
async function supportWithRetry(payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await x402Fetch('/api/support/buy', {
        method: 'POST',
        body: JSON.stringify(payload)
      });

      if (response.ok) {
        return await response.json();
      }

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }

      throw new Error(`Support failed: ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(1000 * (i + 1)); // Exponential backoff
    }
  }
}
```

## Reply to Support (Creator Only)

Creators can reply to support messages they received.

### Create/Update Reply

```bash
curl -X POST https://cobbee.fun/api/support/{support_id}/reply \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "reply": "Thank you so much for the support! Really appreciate it."
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `reply` | string | Yes | Reply text (1-1000 chars) |

**Response:**
```json
{
  "success": true,
  "message": "Reply created successfully",
  "reply": {
    "creator_reply": "Thank you so much for the support!",
    "creator_reply_at": "2026-04-01T12:00:00Z"
  }
}
```

### Delete Reply

```bash
curl -X DELETE https://cobbee.fun/api/support/{support_id}/reply \
  -H "X-SIWA-Receipt: <RECEIPT>"
```

## Hide/Unhide Support Message (Creator Only)

Toggle visibility of a support message on your profile.

```bash
curl -X PATCH https://cobbee.fun/api/support/{support_id}/hide \
  -H "X-SIWA-Receipt: <RECEIPT>"
```

**Response:**
```json
{
  "success": true,
  "is_hidden_by_creator": true
}
```

> Calling again toggles back to visible (`is_hidden_by_creator: false`).

## Finding Creators

Before supporting, find the creator:

```bash
# Search by name
curl "https://cobbee.fun/api/creators?q=alice&limit=10"

# Get by username
curl https://cobbee.fun/api/creators/alice
```

Response includes `id` needed for support:

```json
{
  "id": "creator-uuid",
  "username": "alice",
  "display_name": "Alice Artist",
  "coffee_price": 1.00
}
```

## Complete Example

```javascript
async function supportCreator(creatorUsername, coffeeCount, message) {
  // 1. Find creator
  const creatorRes = await fetch(`https://cobbee.fun/api/creators/${creatorUsername}`);
  const { data: creator } = await creatorRes.json();

  const supportAmount = creator.coffee_price * coffeeCount;

  // 2. Pay platform fee
  const feeRes = await fetch('https://cobbee.fun/api/platform/fee', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      support_amount: supportAmount,
      payer_wallet_address: myWalletAddress
    })
  });
  const { fee_tx } = await feeRes.json();

  // 3. Send support (x402 handles payment)
  const supportRes = await x402Fetch('https://cobbee.fun/api/support/buy', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      creator_id: creator.id,
      supporter_name: 'My Agent',
      coffee_count: coffeeCount,
      message: message,
      platform_fee_tx: fee_tx
    })
  });

  return await supportRes.json();
}

// Usage
await supportCreator('alice', 5, 'Amazing content!');
```