---
name: givegigs-micromoney
description: Manage microMoney (mM), deposit to organizations, sponsor freelancers via Cheap (10% fee) or Secure (25% fee with audit logs) options, and query balance/quota.
---

# GiveGigs - microMoney & Sponsorship (mM)

microMoney (short form unit: **mM**) is GiveGigs' ultra-fine fractional currency for paying for AI actions, server compute, tools, and API requests.
- **1 microMoney = 1 mM = $0.000001 USD** (one millionth of a US dollar).
- **1,000,000 mM = $1.00 USD**.
- Non-admin default allowance: **1,000,000 mM/month ($1.00 USD/month)**.

Future paid mM purchase pricing targets revenue equal to **2× fully allocated costs** (100% markup on cost, 50% profit margin on revenue). Shared infrastructure and payment processing inputs remain configurable. This is a pricing target, not a published pack price; checkout and pack amounts are not currently established.

Business owners can deposit microMoney into organizations or sponsor freelancers and team members so they can run GiveGigs tools and agentic workflows on the business owner's balance without burning through the freelancer's personal quota.

---

### Sponsorship Fee Options

1. **"Cheap" Tier (`tier: "CHEAP"`)**:
   - **Fee**: Exactly **10%** added to consumed action cost (`Math.ceil(cost * 0.10)`).
   - **Audit Logs**: **None**. Zero ledger overhead.
   - **Best for**: Internal trusted agents, high-frequency lightweight tasks, bulk calculations.

2. **"Secure" Tier (`tier: "SECURE"`)**:
   - **Fee**: Exactly **25%** added to consumed action cost (`Math.ceil(cost * 0.25)`).
   - **Audit Logs**: **Full cryptographic audit logging**. Every action writes a SHA-256 chained entry to the immutable ledger with previous hash verification, caller/beneficiary attribution, and tamper detection.
   - **Advanced Configuration**: Set strict spend caps (`spendCapMicroMoney`), restrict allowable actions (`allowedActions`), configure expiration timestamps (`expiresAt`), pause, resume, and revoke.
   - **Best for**: External freelancers, contractor agents, untrusted or multi-tenant team members, enterprise compliance.

---

### Endpoints

#### 1. Query Balance & Sponsorship Status
`GET /api/ai/micromoney/balance`
- **Headers**: `Authorization: Bearer <token>` or `X-API-Key: <key>`
- **Response**:
```json
{
  "userId": "usr_abc123",
  "currency": "microMoney",
  "unit": "mM",
  "balance": {
    "microMoney": 2500000,
    "formatted": "2,500,000 mM ($2.5000)",
    "usd": 2.50
  },
  "monthlyQuota": {
    "limitMicroMoney": 1000000,
    "usedMicroMoney": 45000,
    "remainingMicroMoney": 955000,
    "resetsAt": "2026-11-01T00:00:00.000Z"
  },
  "sponsorships": {
    "granted": [...],
    "received": [...]
  },
  "tiers": {
    "cheap": { "feePercent": 10, "auditLogging": false },
    "secure": { "feePercent": 25, "auditLogging": true }
  }
}
```

#### 2. Create microMoney Sponsorship
`POST /api/ai/micromoney/sponsor`
- **Headers**: `Content-Type: application/json`, `Authorization: Bearer <token>`
- **Payload**:
```json
{
  "beneficiaryUserId": "usr_freelancer_456",
  "tier": "SECURE",
  "spendCapMicroMoney": 500000,
  "allowedActions": "IMAGE_UPSCALE,MUSE_LOT_XRAY,DEFAULT_API_CALL",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "organizationId": null
}
```
- **Fields**:
  - `beneficiaryUserId` *(required)*: Target user or freelancer receiving sponsorship.
  - `tier` *(required)*: `"CHEAP"` (10% fee, no logs) or `"SECURE"` (25% fee, tamper-evident audit logs).
  - `spendCapMicroMoney` *(optional)*: Maximum mM the beneficiary may spend.
  - `allowedActions` *(optional)*: Comma-separated allowlist of actions (e.g. `"IMAGE_UPSCALE,CALCULATOR"`), or `"all"`.
  - `expiresAt` *(optional)*: ISO 8601 future timestamp.

#### 3. Manage Sponsorship (Pause / Resume / Revoke)
`PATCH /api/ai/micromoney/sponsor`
- **Payload**:
```json
{
  "sponsorshipId": "spon_1730000000_abcd",
  "status": "PAUSED"
}
```
- Valid `status` values: `"ACTIVE"`, `"PAUSED"`, `"REVOKED"`. Only the sponsor may modify status.

#### 4. Query Cryptographic Audit Logs (Secure Tier)
`GET /api/ai/micromoney/audit?sponsorshipId=spon_1730000000_abcd&verify=true`
- Returns SHA-256 hash-chained log entries proving timestamp, beneficiary, action name, cost, 25% fee, and cryptographic integrity.

#### 5. Deposit microMoney to Organization Pool
`POST /api/ai/micromoney/organization`
- **Payload**:
```json
{
  "organizationId": "org_design_team",
  "amountMicroMoney": 10000000,
  "tier": "SECURE"
}
```

---

### Standard Action Costs (in mM)

| Action | Server Cost | API / Model Cost | Total Action Cost | With Cheap (10%) | With Secure (25%) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `DEFAULT_API_CALL` | 50 mM | 0 mM | **50 mM** ($0.00005) | **55 mM** | **63 mM** |
| `HEAVY_SERVER_ACTION` | 250 mM | 0 mM | **250 mM** ($0.00025) | **275 mM** | **313 mM** |
| `IMAGE_ANALYZE` | 500 mM | 2,000 mM | **2,500 mM** ($0.00250) | **2,750 mM** | **3,125 mM** |
| `IMAGE_UPSCALE` | 500 mM | 10,000 mM | **10,500 mM** ($0.01050) | **11,550 mM** | **13,125 mM** |
| `MUSE_LOT_XRAY` | 1,000 mM | 15,000 mM | **16,000 mM** ($0.01600) | **17,600 mM** | **20,000 mM** |
| `MUSE_ORCHESTRATE` | 2,000 mM | 25,000 mM | **27,000 mM** ($0.02700) | **29,700 mM** | **33,750 mM** |

`IMAGE_ANALYZE` is an illustrative baseline in this table. The `/api/tools/image/analyze` route currently reserves dynamically from the estimated prompt, image, model, and output usage, so actual reservations vary by request. These action reservation values are internal accounting amounts, not purchase-pack prices.

---

### AI Attack Defenses & Agent Rules

1. **Zero Natural-Language Execution on Financial Ledgers**: Financial mutations only accept strictly validated JSON schemas. No string interpolation or prompt evaluations interact directly with database balances.
2. **Sponsor Authentication Lockdown**: The sponsor account is strictly determined by the authenticated session or verified API key. An agent prompt can never forge or claim a different sponsor identity.
3. **Safe Integer Limits**: All monetary amounts must be positive safe integers (`Number.isSafeInteger(amount) && amount > 0`). Decimals, negative values, exponents, or values over 100,000,000 mM are rejected.
4. **Race Condition & Double-Spend Immunity**: Every reservation uses PostgreSQL row-level locks (`SELECT ... FOR UPDATE`) on both the sponsorship record and the sponsor's account within a single transaction.
5. **Algorithmic Runaway Velocity Limiter**: Caps per-sponsorship activity at 60 requests/minute and 500,000 mM/minute to halt runaway agent loops.