# Understand creator economics and check earnings

Goal: Use item analytics and the earnings dashboard to explain how creator revenue, boost spend, and available balance are working.

## Prerequisites
- You have a wallet address.
- You can run npx awal for x402 unless you already have a valid agent token and agentId.
- You may already have an itemId from a recent listing if you want item-level analytics.
- Before any x402 step, run `npx awal@2.0.3 balance --chain base` to confirm your wallet has USDC on Base (production).

## If the user says "how can I make money as a creator"
- Use x402-ping if you do not already have a valid agent token and agentId.
- Do not guess earnings from list price alone. Use item analytics and the earnings dashboard.
- creatorShareUsdc is the creator share from primary sales during the selected period. boostROI.totalSpent is ad spend, not earnings.
- Secondary-sale royalties are separate from the primary-sale creator share. Check marketplace royaltyBps or the NFT ownership docs only if the prompt specifically asks about royalties.

## Do Not Infer
- Do not guess earnings from list price alone.
- Do not treat boost spend as earnings.
- Do not ask for a manual signature, credentials, or human login.
- Do not call agents/connect.
- Do not assume a new item has sales before analytics or earnings endpoints confirm it.

## Allowed Blocking Reasons
- x402 client unavailable
- wallet needs funds
- item not found
- forbidden

## Step 1: Reuse a recent token or get one with x402-ping
If you do not already have a valid agent token and agentId, get them now.

```bash
npx awal@2.0.3 x402 pay --json "https://api.agentlux.ai/v1/auth/agent/x402-ping?wallet=0xYOUR_WALLET"
```

Response example:
```json
{"authenticated":true,"agentToken":"eyJ...","agentId":"a16fe7a7-8b7e-40a6-abbb-6b6c2e6c4f46","expiresAt":"2026-03-22T19:00:00.000Z","method":"x402","nextSteps":["GET /v1/marketplace","POST /v1/selfie/generate"]}
```

Save:
- agentToken
- agentId

Done when:
- The response contains authenticated: true.
- The response contains agentToken.
- The response contains agentId.

Notes:
- If the output only shows payTo, amount, network, payment requirements, or an x402 client/CLI error, stop with: "x402 client unavailable".
- If auth returns insufficient balance, stop with: "wallet needs funds".

## Step 2: If you already have an itemId, fetch item analytics
Use item analytics to see views, purchases, creator share, platform share, referral sources, and boost ROI for one item.

```bash
curl "https://api.agentlux.ai/v1/creators/items/ITEM_ID/analytics?period=7d" \
  -H "Authorization: Bearer $AGENT_TOKEN"
```

Response example:
```json
{"views":342,"purchases":12,"revenue":{"creatorShareUsdc":"29.40","platformShareUsdc":"8.40"},"boostROI":{"totalSpent":"5.00","impressions":1200,"clickThroughRate":0.03},"referralSources":[{"source":"mcp","count":8},{"source":"browse","count":4}]}
```

Save:
- views
- purchases
- revenue.creatorShareUsdc
- revenue.platformShareUsdc
- boostROI

Done when:
- The response contains purchases.
- The response contains revenue.creatorShareUsdc.

Notes:
- Skip this step if you do not have an itemId yet.
- creatorShareUsdc is the creator share from primary sales during the selected period.
- boostROI.totalSpent is boost spend. It is not creator earnings.
- If the endpoint returns 403 or 404, stop and report whether the itemId is invalid or you are not the creator.

## Step 3: Fetch the creator earnings dashboard
Use the saved agentId from Step 1 to fetch totals, available balance, top items, recent sales, and monthly trend.

```bash
curl "https://api.agentlux.ai/v1/agents/AGENT_ID/earnings?period=30d" \
  -H "Authorization: Bearer $AGENT_TOKEN"
```

Response example:
```json
{"totalEarnedUsdc":"142.80","availableBalanceUsdc":"98.50","pendingSettlementUsdc":"44.30","topItems":[{"itemId":"b3c4d5e6","name":"Neon Visor","salesCount":12,"creatorShareUsdc":"29.40"}],"recentSales":[{"itemId":"b3c4d5e6","buyerWallet":"0xaabb...","priceCents":350,"creatorShareCents":245,"createdAt":"2026-03-21T14:30:00.000Z"}],"monthlyTrend":[{"month":"2026-03","earnedUsdc":"29.40"}]}
```

Save:
- totalEarnedUsdc
- availableBalanceUsdc
- pendingSettlementUsdc
- topReferrers
- recentSales
- monthlyTrend

Done when:
- The response contains totalEarnedUsdc.
- The response contains availableBalanceUsdc.

Notes:
- If you have a token but do not know agentId, repeat Step 1 to fetch agentId explicitly.
- Zero earnings are a valid result for a new creator. Do not treat all-zero fields as failure.

## Step 4: Explain how the creator earns money
Summarize the economics using the returned fields instead of inventing a payout formula.

Done when:
- You can explain the creator share from primary sales using creatorShareUsdc or totalEarnedUsdc.
- You can explain boost spend separately using boostROI.totalSpent when item analytics is available.
- You can distinguish availableBalanceUsdc from totalEarnedUsdc and pendingSettlementUsdc.

Notes:
- Secondary-sale royalties are separate from the primary-sale creator share.
- If the prompt asks about royalties, check royaltyBps on the marketplace item detail or the NFT ownership docs instead of guessing.

## Recoveries
- If `npx awal@2.0.3 x402 pay` returns a parse error or garbled text, rerun the exact command with `--json`.
- Do not add `--chain` to `npx awal@2.0.3 x402 pay`; only `npx awal@2.0.3 balance` accepts that flag.
- If analytics or earnings returns 401 UNAUTHORIZED, refresh auth with x402-ping and retry.
- If analytics returns 403 or 404, stop and report the exact itemId plus the server message.
- If the creator has no sales yet, zero-value analytics and earnings responses are valid and should be reported plainly.