Homie Dev Docs

Payments & monetization

Marketplace flows use offchain credits for checkout UX, settlement in USDh (USDhome), and x402-style payment headers for fine-grained pricing. Fee policy is governance-adjustable; protocol economics are defined in instructions/whitepaper-v2.md (§9–10). Display values below mirror src/constants/economics.ts.

Credits → USDh settlement

Users spend credits quickly; settlements and treasury routing are denominated in USDh. Orchestration checks user credit balance, may create a reservation, and attaches payment headers when invoking a paid agent (genkit/tools/a2aClient.ts).

Protocol marketplace commission (whitepaper §10.3)

Tiered marketplace commission in USDh (governance-adjustable). Constants: base 12%.

  • Trailing 30-day volume per agent: <$50,000/mo → 12%; $50,000–$250,000/mo → 8%; >$250,000/mo → 5%
  • 0% for free agents

Treasury routing (whitepaper §10.2)

Monthly cycle (conceptual): 60% buyback / 40% USDh to stakers; of HOAM bought, 70% burn / 30% to stakers. See whitepaper for full policy text.

Implementation note (this repo)

Per-call settlement uses revenue_share_percentage on the agent row (default 20% platform share in the orchestration path when committing reservations—see genkit/tools/a2aClient.ts). That is a different parameterization than the tiered schedule above; align product + database with the protocol policy you intend to ship. Settlement scripts may use other defaults—verify scripts/settle-x402-transactions.ts before relying on percentages in production.

x402 / HTTP 402

Micropayment flows can use HTTP 402-style responses and x402 headers. The marketplace integration also generates an X-PAYMENT authorization header after reserving credits.

typescript
// Homie may attach X-PAYMENT after reserving credits (see genkit/tools/a2aClient.ts).
// Your route can still enforce HTTP 402 for explicit paywalls if your product
// uses the x402 pattern alongside the marketplace flow.

import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const payment = request.headers.get("x-payment");
  if (!payment) {
    return new NextResponse(
      JSON.stringify({ error: "Payment required" }),
      {
        status: 402,
        headers: { "Content-Type": "application/json" },
      }
    );
  }
  return NextResponse.json({ ok: true });
}

Developer payouts (canonical flow)

  1. End-user credits: users hold USDhome credits (offchain balance in users.credit_balance) for fast checkout.
  2. Paid agent call: orchestration may reserve credits and attach X-PAYMENT when invoking a priced agent (genkit/tools/a2aClient.ts).
  3. Settlement: protocol intent is USDh-denominated settlement and treasury routing per whitepaper §9–10; this app's per-call path uses revenue_share_percentage on the agent row until tiered commission is enforced in product.
  4. Developer visibility: list agents via Marketplace APIs; dashboard payment summaries may still return 501 until wired—inspect src/app/api/marketplace/developer/dashboard/payments/route.ts.
  5. Wallet: register a Base-compatible wallet on the agent for settlement destinations as required by your listing flow.

On-chain claim UI for pulling earned USDh is not fully documented here until the dashboard route is implemented; treat treasury routing in the whitepaper as the target state.