Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// MonetizationService — one place for skill-monetization business logic.
//
// Before this, the rules for "what does a skill cost", "who may change a
// price", "build a purchase", "confirm a payment", "does this user own a
// skill", and "what has a creator earned" were spread across half a dozen API
// handlers, each re-deriving ownership checks, fee splits, and payout lookups.
// This class is the single seam those handlers call through, so the policy
// lives in one tested unit and the handlers shrink to HTTP plumbing
// (auth → validate → call service → map result/error to a response).
//
// It does not reinvent the lower-level primitives — payout resolution, on-chain
// confirmation, access checks, fee math, and balance accounting already have
// dedicated, tested modules. The service orchestrates them and owns the
// handler-shaped business rules (ownership gating, idempotent purchase create,
// already-owned short-circuit) that previously lived inline.
//
// Errors are thrown with `status` (HTTP code) and `code` (machine string) so a
// handler can map them with `error(res, e.status, e.code, e.message)` without
// knowing the internals.
import { Keypair } from '@solana/web3.js';
import { sql as defaultSql } from '../db.js';
import { hasSkillAccess } from '../skill-access.js';
import { getAvailableBalance } from '../monetization.js';
import { resolveMarketplaceFee } from '../marketplace-platform-fee.js';
import { resolveListingSplit, describeSplit } from '../splits.js';
import { resolveSkillPrice } from '../skill-pricing-rules.js';
import { invalidateSkillPriceCache } from '../skill-price-cache.js';
import {
confirmSkillPurchase,
resolvePayoutAddress,
logEvent,
} from '../purchase-confirm.js';
// Build an Error that carries the HTTP status + machine code a handler maps from.
function svcError(status, code, message) {
return Object.assign(new Error(message), { status, code });
}
/**
* Hours of access a purchase grants. A skill with a fixed time-pass price sells
* exactly its configured window, whatever duration the caller asked for;
* otherwise a caller-chosen duration could stretch a cheap pass to any length.
* PWYW purchases are permanent and have no window.
*/
export function resolveAccessHours(price, requestedHours, isPwyw) {
if (isPwyw) return null;
if (price.time_pass_amount) return price.time_pass_hours || null;
return requestedHours ?? (price.time_pass_hours || null);
}
export class MonetizationService {
/**
* @param {object|string|null} user - a session user ({ id }), an auth object
* ({ userId }), a raw user-id string, or null for anonymous callers.
* @param {object} [deps] - injectable dependencies (mainly for tests).
* @param {object} [deps.sql] - tagged-template SQL client; defaults to the
* shared Neon client.
*/
constructor(user, deps = {}) {
this.user = user ?? null;
this.userId =
typeof user === 'string' ? user : user?.id ?? user?.userId ?? null;
this.sql = deps.sql || defaultSql;
}
requireAuth() {
if (!this.userId) throw svcError(401, 'unauthorized', 'sign in required');
return this.userId;
}
/**
* Load an agent and assert the current user owns it.
* @returns {Promise<{id: string, user_id: string}>}
* @throws 401 if anonymous, 404 if missing, 403 if not the owner.
*/
async assertOwnership(agentId) {
this.requireAuth();
const [agent] = await this.sql`
SELECT id, user_id FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!agent) throw svcError(404, 'not_found', 'agent not found');
if (agent.user_id !== this.userId) {
throw svcError(403, 'forbidden', 'not your agent');
}
return agent;
}
/**
* Active per-skill prices for an agent. Pure read — callers decide whether the
* surface is public (marketplace) or owner-gated (dashboard).
*/
async getSkillPricesForAgent(agentId) {
return this.sql`
SELECT skill, amount, currency_mint, chain, mint_decimals,
trial_uses, time_pass_hours, time_pass_amount,
pricing_type, minimum_amount,
gate_type, nft_collection_mint
FROM agent_skill_prices
WHERE agent_id = ${agentId} AND is_active = true
ORDER BY skill
`;
}
/**
* Atomically replace the agent's active price set with the submitted prices.
* Deactivates everything currently active, then upserts the submitted rows in
* one transaction. Input is expected to be already validated by the caller.
*
* @param {string} agentId
* @param {Array<{skill,amount,currency_mint,chain,trial_uses?,time_pass_hours?,time_pass_amount?}>} prices
* @param {object} [opts]
* @param {boolean} [opts.skipOwnershipCheck] - set when the caller already
* verified ownership (avoids a redundant lookup).
*/
async setSkillPrices(agentId, prices, { skipOwnershipCheck = false } = {}) {
if (!skipOwnershipCheck) await this.assertOwnership(agentId);
// Neon's serverless driver runs a transaction as an ARRAY of queries in a
// single round-trip. Every statement is known up front, so we build the
// array and pass it. Atomic: the deactivate + all upserts commit together
// or not at all.
const statements = [
this.sql`UPDATE agent_skill_prices SET is_active = false WHERE agent_id = ${agentId}`,
...prices.map(
(p) => {
const isNft = p.gate_type === 'nft';
return this.sql`
INSERT INTO agent_skill_prices
(agent_id, skill, amount, currency_mint, chain, is_active, trial_uses,
time_pass_hours, time_pass_amount, pricing_type, minimum_amount,
gate_type, nft_collection_mint)
VALUES
(${agentId}, ${p.skill}, ${isNft ? 0 : p.amount}, ${p.currency_mint}, ${p.chain}, true,
${isNft ? 0 : (p.trial_uses ?? 0)}, ${isNft ? null : (p.time_pass_hours ?? null)},
${isNft ? null : (p.time_pass_amount ?? null)},
${isNft ? 'fixed' : (p.pricing_type === 'pwyw' ? 'pwyw' : 'fixed')},
${isNft ? null : (p.pricing_type === 'pwyw' ? (p.minimum_amount ?? 0) : null)},
${isNft ? 'nft' : 'price'},
${isNft ? p.nft_collection_mint : null})
ON CONFLICT (agent_id, skill) DO UPDATE SET
amount = EXCLUDED.amount,
currency_mint = EXCLUDED.currency_mint,
chain = EXCLUDED.chain,
is_active = true,
trial_uses = EXCLUDED.trial_uses,
time_pass_hours = EXCLUDED.time_pass_hours,
time_pass_amount = EXCLUDED.time_pass_amount,
pricing_type = EXCLUDED.pricing_type,
minimum_amount = EXCLUDED.minimum_amount,
gate_type = EXCLUDED.gate_type,
nft_collection_mint = EXCLUDED.nft_collection_mint,
updated_at = now()
`;
},
),
];
await this.sql.transaction(statements);
await invalidateSkillPriceCache(agentId);
return { ok: true, count: prices.length };
}
/**
* Prepare a Solana-Pay skill purchase for the current user. Resolves the
* price + payout wallet, computes the platform-fee split, short-circuits if
* the user already has active access, reuses a still-valid pending row
* (idempotent), and otherwise records a new pending purchase.
*
* Returns the payment quote the client signs against (reference, recipient,
* amounts, fee leg, time-pass window). Despite the name it returns Solana-Pay
* parameters rather than a serialized transaction — the wallet builds the tx
* from these; the serialized-tx variant lives in payments/prepare-skill-purchase.
*
* Gifting: pass `recipientUserId` to buy the skill for someone else. The
* payer stays in `user_id` (they sign + confirm the payment); the recipient
* is recorded in `recipient_user_id` and is the one who receives access. The
* already-owned check and the access grant both key off the beneficiary
* (`COALESCE(recipient_user_id, user_id)`), so a buyer may gift the same skill
* to many distinct recipients without colliding with their own copy.
*
* @param {string} agentId
* @param {string} skillName
* @param {object} [opts]
* @param {number|null} [opts.durationHours] - explicit time-pass length.
* @param {string|null} [opts.referrerUserId] - resolved referrer (handler reads the request).
* @param {string|null} [opts.recipientUserId] - gift beneficiary (resolved by the handler).
*/
async preparePurchaseTransaction(agentId, skillName, { durationHours = null, referrerUserId = null, recipientUserId = null, payAmount = null } = {}) {
this.requireAuth();
const isGift = !!recipientUserId && recipientUserId !== this.userId;
if (recipientUserId && recipientUserId === this.userId) {
throw svcError(400, 'cannot_gift_self', 'you already own purchases you make for yourself');
}
const beneficiaryId = isGift ? recipientUserId : this.userId;
const [price] = await this.sql`
SELECT amount, currency_mint, chain, mint_decimals, trial_uses,
time_pass_hours, time_pass_amount, pricing_type, minimum_amount
FROM agent_skill_prices
WHERE agent_id = ${agentId} AND skill = ${skillName} AND is_active = true
`;
if (!price) throw svcError(404, 'not_found', 'this skill is not for sale');
const isPwyw = price.pricing_type === 'pwyw';
// Dynamic pricing rules (first-N-free proof phases, post-traction step-ups,
// time windows) override the base amount for fixed-price skills. This is
// the same engine the creator dashboard writes rules into: quoting from
// the base table alone would advertise promos that never apply.
if (!isPwyw) {
const effective = await resolveSkillPrice(agentId, skillName).catch(() => null);
if (effective && effective.amount != null) {
price.amount = effective.amount;
}
}
let payoutAddress = await resolvePayoutAddress(agentId, price.chain);
// Proceeds split: a multi-collaborator listing shows the buyer where money
// goes ("proceeds split: 70/30"). For an on-chain (0xSplits, EVM) split the
// creator's net is routed INTO the split contract, so the recipient the
// buyer pays becomes the split address — confirm verifies against the same.
const listingSplit = await resolveListingSplit(this.sql, agentId, skillName).catch(() => null);
if (listingSplit?.split_mode === 'onchain' && listingSplit.split_address && price.chain !== 'solana') {
payoutAddress = listingSplit.split_address;
}
if (!payoutAddress) {
throw svcError(412, 'creator_wallet_missing', 'agent owner has not configured a payout wallet');
}
// Already-owned short-circuit: any active access (confirmed purchase, live
// trial, unexpired time-pass) the BENEFICIARY already holds returns early so
// nobody pays twice. For a gift this means "the recipient already owns it" —
// the buyer is told without their own ownership leaking into the answer.
const [existing] = await this.sql`
SELECT reference, status, tx_signature, confirmed_at, valid_until, trial_remaining, kind
FROM skill_purchases
WHERE COALESCE(recipient_user_id, user_id) = ${beneficiaryId}
AND agent_id = ${agentId} AND skill = ${skillName}
AND status IN ('confirmed', 'trial')
AND (valid_until IS NULL OR valid_until > now())
ORDER BY (status = 'confirmed') DESC, confirmed_at DESC NULLS LAST
LIMIT 1
`;
if (existing) {
if (isGift) {
// Don't surface the recipient's own purchase reference / tx to the buyer.
return { already_owned: true, recipient_owns: true };
}
return {
already_owned: true,
reference: existing.reference,
status: existing.status,
tx_signature: existing.tx_signature,
confirmed_at: existing.confirmed_at,
valid_until: existing.valid_until,
trial_remaining: existing.trial_remaining,
kind: existing.kind,
};
}
// Idempotent create: reuse a fresh pending row for the same (buyer, agent,
// skill, recipient) rather than minting a new reference on every retry click.
// `IS NOT DISTINCT FROM` matches a NULL recipient (self-purchase) too, and
// keeps gifts to different recipients on their own pending rows.
const [pending] = await this.sql`
SELECT reference, amount, currency_mint, chain, expires_at,
platform_fee_amount, platform_fee_wallet
FROM skill_purchases
WHERE user_id = ${this.userId} AND agent_id = ${agentId} AND skill = ${skillName}
AND recipient_user_id IS NOT DISTINCT FROM ${recipientUserId}
AND status = 'pending'
AND expires_at > now()
ORDER BY created_at DESC
LIMIT 1
`;
// Time-pass: prefer an explicit duration, else the skill's configured window.
// PWYW is a permanent-purchase pricing mode and takes precedence over the
// time-pass path — a buyer who names their own price is buying the skill
// outright, not renting a window.
const effectiveDurationHours = resolveAccessHours(price, durationHours, isPwyw);
const isTimePass = effectiveDurationHours != null;
// Resolve the amount the buyer will be charged. Fixed skills bill the
// listed price (or the time-pass price). PWYW skills bill the buyer-chosen
// `payAmount`, validated against the configured minimum and a sane ceiling.
let purchaseAmount;
if (isPwyw) {
// resolvePwywAmount returns a BigInt; normalize to a string so every
// downstream SQL interpolation matches the fixed/time-pass branches.
purchaseAmount = this.resolvePwywAmount(payAmount, price).toString();
} else if (isTimePass && price.time_pass_amount) {
purchaseAmount = price.time_pass_amount;
} else {
purchaseAmount = price.amount;
}
const purchaseKind = isTimePass ? 'time_pass' : 'purchase';
// Platform fee (Solana only — the split is one atomic SPL transfer the buyer
// signs). Computed once at create and persisted on the row so confirm
// verifies the exact split quoted, even if fee config changes meanwhile.
const feeInfo = price.chain === 'solana'
? await resolveMarketplaceFee({ grossAtomics: BigInt(purchaseAmount) })
: null;
const platformFeeAmount = feeInfo ? feeInfo.feeAtomics : 0n;
const platformFeeWallet = feeInfo ? feeInfo.recipient.toBase58() : null;
const reference = pending?.reference ?? Keypair.generate().publicKey.toBase58();
const label = isTimePass
? `${effectiveDurationHours}h Access: ${skillName.slice(0, 30)}`
: `Skill: ${skillName.slice(0, 40)}`;
const message = isTimePass
? `Get ${effectiveDurationHours}-hour access to '${skillName}'`
: `Unlock '${skillName}' for this agent`;
let row = pending;
if (!pending) {
const validUntil = isTimePass
? this.sql`now() + (${effectiveDurationHours} || ' hours')::interval`
: this.sql`null`;
const [inserted] = await this.sql`
INSERT INTO skill_purchases (
user_id, agent_id, skill, status, reference,
amount, currency_mint, chain, expires_at, kind, referrer_user_id, valid_until,
platform_fee_amount, platform_fee_wallet, recipient_user_id
)
VALUES (
${this.userId}, ${agentId}, ${skillName}, 'pending', ${reference},
${purchaseAmount}, ${price.currency_mint}, ${price.chain},
now() + interval '30 minutes', ${purchaseKind}, ${referrerUserId}, ${validUntil},
${platformFeeAmount.toString()}, ${platformFeeWallet}, ${recipientUserId}
)
RETURNING reference, amount, currency_mint, chain, expires_at, valid_until,
platform_fee_amount, platform_fee_wallet
`;
row = inserted;
await logEvent(row.reference, 'created', { agent_id: agentId, skill: skillName, kind: purchaseKind, gift: isGift });
} else if (isPwyw && BigInt(pending.amount) !== BigInt(purchaseAmount)) {
// PWYW: the buyer changed their chosen amount on a retry. Re-sync the
// reused pending row (and its persisted fee split) so the quote — and the
// on-chain amount confirm verifies against — match the NEW amount.
const [resynced] = await this.sql`
UPDATE skill_purchases
SET amount = ${purchaseAmount},
platform_fee_amount = ${platformFeeAmount.toString()},
platform_fee_wallet = ${platformFeeWallet},
expires_at = now() + interval '30 minutes'
WHERE reference = ${pending.reference} AND status = 'pending'
RETURNING reference, amount, currency_mint, chain, expires_at, valid_until,
platform_fee_amount, platform_fee_wallet
`;
row = resynced ?? pending;
await logEvent(pending.reference, 'pwyw_amount_updated', { agent_id: agentId, skill: skillName, amount: String(purchaseAmount) });
} else {
await logEvent(pending.reference, 'create_idempotent_hit', { agent_id: agentId, skill: skillName });
}
// The split the buyer signs, derived from the PERSISTED row so the quote
// matches exactly what confirm verifies on-chain. `amount` is the full
// price; `creator_amount` is the seller's leg; `fee` is the treasury leg
// (omitted entirely when no fee applies).
const rowFee = BigInt(row.platform_fee_amount || 0);
const creatorAmount = (BigInt(row.amount) - rowFee).toString();
const feeBlock = rowFee > 0n && row.platform_fee_wallet
? {
fee: {
recipient: row.platform_fee_wallet,
amount: rowFee.toString(),
bps: Number((rowFee * 10000n) / BigInt(row.amount)),
},
}
: {};
// Buyer-facing split disclosure: who shares the creator's net, and how.
const splitBlock = listingSplit?.recipients?.length
? {
split: {
mode: listingSplit.split_mode,
address: listingSplit.split_address,
creator_net: creatorAmount,
...describeSplit(listingSplit.recipients),
},
}
: {};
return {
already_owned: false,
reference: row.reference,
recipient: payoutAddress,
amount: String(row.amount),
creator_amount: creatorAmount,
currency_mint: row.currency_mint,
chain: row.chain,
mint_decimals: price.mint_decimals,
expires_at: row.expires_at,
valid_until: row.valid_until,
kind: purchaseKind,
label,
message,
...feeBlock,
...splitBlock,
...(isGift ? { is_gift: true, gift_recipient_id: recipientUserId } : {}),
...(isTimePass ? { duration_hours: effectiveDurationHours } : {}),
...(price.time_pass_hours && !isPwyw
? { time_pass_hours: price.time_pass_hours, time_pass_amount: price.time_pass_amount }
: {}),
...(isPwyw
? {
pricing_type: 'pwyw',
minimum_amount: String(price.minimum_amount ?? 0),
suggested_amount: String(price.amount),
}
: {}),
};
}
/**
* Validate and normalize a buyer-supplied "pay what you want" amount against a
* PWYW skill's price row. Returns the atomic-units amount to charge.
*
* Rules:
* • Must be a finite, non-negative integer in atomic units.
* • Must be ≥ the configured `minimum_amount` (NULL/0 means no floor).
* • Must not exceed a sane ceiling (1,000,000 whole tokens, scaled by the
* mint's decimals) — a guard against fat-finger / overflow inputs, not a
* business cap.
* • Omitted (`null`) defaults to the suggested price (`amount`) only when
* that already satisfies the minimum; otherwise the buyer must choose.
*
* @param {string|number|bigint|null} payAmount - buyer-chosen atomic amount.
* @param {{amount:any, minimum_amount:any, mint_decimals:number}} price
* @returns {bigint} amount in atomic units to charge
* @throws 400 invalid_amount / amount_below_minimum / amount_too_large
*/
resolvePwywAmount(payAmount, price) {
const minimum = price.minimum_amount == null ? 0n : BigInt(price.minimum_amount);
const decimals = Number(price.mint_decimals ?? 6);
const ceiling = 1_000_000n * 10n ** BigInt(Number.isFinite(decimals) ? decimals : 6);
let chosen;
if (payAmount == null || payAmount === '') {
// No explicit amount — fall back to the suggested price if it clears the
// minimum; otherwise require the buyer to name a figure.
const suggested = BigInt(price.amount ?? 0);
if (suggested < minimum) {
throw svcError(400, 'invalid_amount', 'choose how much to pay for this skill');
}
chosen = suggested;
} else {
let parsed;
try {
// Reject decimals / non-integers up front: atomic units are whole.
const s = String(payAmount).trim();
if (!/^\d+$/.test(s)) throw new Error('not an integer');
parsed = BigInt(s);
} catch {
throw svcError(400, 'invalid_amount', 'amount must be a whole number of atomic units');
}
chosen = parsed;
}
if (chosen < 0n) throw svcError(400, 'invalid_amount', 'amount cannot be negative');
if (chosen < minimum) {
throw svcError(400, 'amount_below_minimum', 'amount is below this skill’s minimum');
}
// A purchase must move value: a zero-amount "purchase" can't be verified
// on-chain. A creator who wants a free skill should not list a price at all.
if (chosen === 0n) {
throw svcError(400, 'invalid_amount', 'amount must be greater than zero');
}
if (chosen > ceiling) {
throw svcError(400, 'amount_too_large', 'amount exceeds the maximum allowed');
}
return chosen;
}
/**
* Confirm a pending purchase the current user owns, identified by its
* Solana-Pay reference. Solana scans the chain by reference; EVM settles by a
* tx hash the buyer submits.
*
* @param {string} reference
* @param {object} [opts]
* @param {string|null} [opts.txHash] - settlement tx hash (required for EVM).
* @returns {Promise<{status:'pending'|'confirmed'|'tipped'|'mismatch', tx_signature?:string, tipped_amount?:string, message?:string}>}
* @throws 404 if not found, 410 if expired, 400 if an EVM confirm omits tx_hash.
*/
async confirmPurchase(reference, { txHash = null } = {}) {
this.requireAuth();
const [pur] = await this.sql`
SELECT sp.id, sp.user_id, sp.agent_id, sp.skill, sp.status,
sp.amount, sp.currency_mint, sp.chain, sp.tx_signature,
sp.expires_at, sp.referrer_user_id, sp.recipient_user_id,
sp.platform_fee_amount, sp.platform_fee_wallet,
COALESCE(asp.mint_decimals, 6) AS mint_decimals
FROM skill_purchases sp
LEFT JOIN agent_skill_prices asp
ON asp.agent_id = sp.agent_id AND asp.skill = sp.skill
WHERE sp.reference = ${reference} AND sp.user_id = ${this.userId}
`;
if (!pur) throw svcError(404, 'not_found', 'purchase not found');
if (pur.status === 'confirmed') {
return { status: 'confirmed', tx_signature: pur.tx_signature };
}
if (pur.status === 'expired' || (pur.expires_at && new Date(pur.expires_at) < new Date())) {
throw svcError(410, 'purchase_expired', 'this pending purchase expired; please start a new one');
}
if (pur.chain !== 'solana' && !txHash) {
throw svcError(400, 'tx_hash_required', 'tx_hash is required to confirm an EVM purchase');
}
return confirmSkillPurchase({ ...pur, reference }, { txHash });
}
/**
* Does the current user have access to a paid skill on an agent? Delegates to
* the canonical access check, so trials, time-passes, and agent-level
* subscriptions all count — not just confirmed one-off purchases.
*
* @returns {{has_access:boolean, paid:boolean, owned:boolean, reason?:string,
* trial?:boolean, trial_remaining?:number, via_subscription?:boolean, price?:object}}
*/
async checkSkillOwnership(agentId, skillName) {
const access = await hasSkillAccess(this.userId, agentId, skillName);
return { has_access: !!access.owned, ...access };
}
/**
* Creator sales overview for the current user: per-sale ledger entries (skill
* royalties + asset sales) plus pending/settled USD totals.
*
* Both royalty lanes land here. Rows billed in-process by skill-runtime carry
* an agent_id and settle later through the EIP-7710 redeem leg; rows accrued
* on the platform's own x402 rail (/api/x402/skill-call) have NO agent_id at
* all, because the caller is an anonymous paying wallet rather than a
* registered agent. Both joins are therefore LEFT joins: an inner join on
* agent_identities silently dropped every per-call x402 royalty from this
* surface, so authors earning on the rail saw an empty ledger and a $0 total.
*
* @returns {Promise<{pending_usd:number, settled_usd:number, entries:Array}>}
*/
async getCreatorSalesData() {
const userId = this.requireAuth();
const rows = await this.sql`
SELECT
rl.id,
rl.price_usd,
rl.status,
rl.created_at,
rl.settled_at,
rl.source,
rl.network,
rl.tx_hash,
rl.platform_fee_usd,
ms.name AS skill_name,
ms.slug AS skill_slug,
ai.name AS agent_name
FROM royalty_ledger rl
LEFT JOIN marketplace_skills ms ON ms.id = rl.skill_id
LEFT JOIN agent_identities ai ON ai.id = rl.agent_id
WHERE rl.author_user_id = ${userId}
ORDER BY rl.created_at DESC
LIMIT 100
`;
// Asset sales (avatars / agents / plugins). asset_purchases stores amount
// in atomic USDC units (6 decimals) — divide for USD reporting.
let assetRows = [];
try {
assetRows = await this.sql`
SELECT
ap.id,
ap.item_type,
ap.item_id,
ap.amount,
ap.currency_mint,
ap.confirmed_at,
ap.created_at,
ap.status,
CASE ap.item_type
WHEN 'avatar' THEN (SELECT name FROM avatars WHERE id = ap.item_id)
WHEN 'agent' THEN (SELECT name FROM agent_identities WHERE id = ap.item_id)
ELSE NULL
END AS item_name
FROM asset_purchases ap
WHERE ap.seller_user_id = ${userId}
AND ap.status = 'confirmed'
ORDER BY ap.confirmed_at DESC NULLS LAST
LIMIT 100
`;
} catch {
// asset_purchases migration hasn't run yet — leave list empty.
}
const sumBy = (status) => rows
.filter((r) => r.status === status)
.reduce((s, r) => s + Number(r.price_usd), 0);
const pending_usd = sumBy('pending');
// Claimed by an in-flight settle pass: no longer 'pending', not yet in the
// author's wallet. Reported separately so neither total overstates itself.
const settling_usd = sumBy('settling');
const settled_usd = sumBy('settled');
// What the platform kept across these rows. Only the x402 rail records a
// per-row cut; runtime rows leave it null and contribute 0.
const platform_fee_usd = rows.reduce((s, r) => s + Number(r.platform_fee_usd ?? 0), 0);
const asset_settled_usd = assetRows.reduce((s, r) => s + Number(r.amount) / 1_000_000, 0);
const entries = rows.map((r) => ({
skill_name: r.skill_name,
skill_slug: r.skill_slug ?? null,
agent_name: r.agent_name,
price_usd: Number(r.price_usd),
platform_fee_usd: r.platform_fee_usd == null ? null : Number(r.platform_fee_usd),
status: r.status,
created_at: r.created_at,
settled_at: r.settled_at ?? null,
// Which rail earned it: 'x402' (per-call, paid straight to the author's
// wallet at settle) or 'skill-runtime' (in-process, settles via the
// flag-gated EIP-7710 redeem leg).
source: r.source ?? 'skill-runtime',
network: r.network ?? null,
tx_hash: r.tx_hash ?? null,
kind: 'skill',
}));
for (const r of assetRows) {
entries.push({
skill_name: `${r.item_type[0].toUpperCase()}${r.item_type.slice(1)} sale`,
skill_slug: null,
agent_name: r.item_name || '(deleted)',
price_usd: Number(r.amount) / 1_000_000,
platform_fee_usd: null,
status: 'settled',
created_at: r.confirmed_at || r.created_at,
settled_at: r.confirmed_at || null,
source: 'asset-sale',
network: null,
tx_hash: null,
kind: r.item_type,
});
}
entries.sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
return {
pending_usd,
settling_usd,
settled_usd: settled_usd + asset_settled_usd,
platform_fee_usd,
entries,
};
}
/**
* Withdrawable balance for the current user across (or filtered to) a
* currency. Thin pass-through to the accounting helper so handlers reach
* balance state through the same service seam as everything else.
*/
async getAvailableBalance(currencyMint = null) {
const userId = this.requireAuth();
return getAvailableBalance(userId, currencyMint);
}
/**
* The single "what I earned, what split where, what I can withdraw" surface
* for the creator dashboard. Composes the sales ledger (getCreatorSalesData)
* with: the split allocations this user received, the on-chain skill licenses
* their skills minted to buyers, and their withdrawable balance — all
* reconciled to the same revenue/withdrawal ledger buyers are billed from.
*
* @returns {Promise<{
* pending_usd:number, settling_usd:number, settled_usd:number,
* platform_fee_usd:number, entries:Array,
* splits:{ received_usd:number, distributions:Array },
* onchain_licenses:{ minted:number, by_agent:Array },
* withdrawable:{ available:number, earned:number, pending:number, withdrawn:number }
* }>}
*/
async getCreatorEconomics() {
const userId = this.requireAuth();
const sales = await this.getCreatorSalesData();
// Split allocations this user received (as a collaborator). Atomic USDC
// (6 decimals) → USD for display. Best-effort: pre-migration DBs return [].
let splitRows = [];
try {
splitRows = await this.sql`
SELECT sd.amount, sd.share_bps, sd.currency_mint, sd.mode, sd.status,
sd.tx_signature, sd.created_at, sd.chain,
sp.skill AS skill_name, ai.name AS agent_name
FROM split_distributions sd
JOIN skill_purchases sp ON sp.id = sd.purchase_id
LEFT JOIN agent_identities ai ON ai.id = sp.agent_id
WHERE sd.recipient_user_id = ${userId}
ORDER BY sd.created_at DESC
LIMIT 100
`;
} catch {
splitRows = [];
}
const received_usd = splitRows.reduce((s, r) => s + Number(r.amount) / 1_000_000, 0);
const distributions = splitRows.map((r) => ({
skill_name: r.skill_name,
agent_name: r.agent_name || '(deleted)',
amount_usd: Number(r.amount) / 1_000_000,
share_bps: r.share_bps,
percent: Math.round((r.share_bps / 100) * 100) / 100,
mode: r.mode,
status: r.status,
chain: r.chain,
tx_signature: r.tx_signature,
created_at: r.created_at,
}));
// On-chain skill licenses this creator's skills minted to buyers.
let licenses = { minted: 0, by_agent: [] };
try {
const rows = await this.sql`
SELECT ai.name AS agent_name, slm.agent_id,
COUNT(*) FILTER (WHERE slm.status IN ('minted', 'already'))::int AS minted
FROM skill_license_mints slm
JOIN agent_identities ai ON ai.id = slm.agent_id
WHERE ai.user_id = ${userId}
GROUP BY slm.agent_id, ai.name
HAVING COUNT(*) FILTER (WHERE slm.status IN ('minted', 'already')) > 0
ORDER BY minted DESC
`;
licenses = {
minted: rows.reduce((s, r) => s + Number(r.minted), 0),
by_agent: rows.map((r) => ({ agent_id: r.agent_id, agent_name: r.agent_name, minted: Number(r.minted) })),
};
} catch {
licenses = { minted: 0, by_agent: [] };
}
const bal = await getAvailableBalance(userId);
const withdrawable = {
available: bal.available / 1_000_000,
earned: bal.earned / 1_000_000,
pending: bal.pending / 1_000_000,
withdrawn: bal.withdrawn / 1_000_000,
};
return {
...sales,
splits: { received_usd, distributions },
onchain_licenses: licenses,
withdrawable,
};
}
}
export default MonetizationService;