Deposit match promo — bonus credit on first qualifying top-up

account credit on a qualifying USDC prepay or x402 top-up.

What counts as a qualifying deposit?

A qualifying deposit is USDC that lands in the agent’s virtual balance through one of the two promo-eligible refill paths, meets the amount rules for that moment in the promo lifecycle, and passes IP / anti-farming checks when the grant is applied.

Eligible refill paths

Both paths credit virtual_balance_usd the same way as normal prepay — promo only adds bonus credit on top when the rules below are met:

  1. USDC prepay — user sends USDC on Base to the prepay receive address from a linked wallet, then POST /api/v1/balance/deposit/claim (or the SPA at /connect?action=topup). See /cookbook/prepay_deposits.
  2. x402 top-up — POST /api/v1/balance/topup/x402 with a settled PAYMENT-SIGNATURE on Base.

Mint grants, session-feedback credits, bill-on-match refunds, and x402 route settlements (paying for an enrichment call directly) are not qualifying deposits — they do not lock a tier and do not unlock pool slices.

Amount rules (three different moments)

Moment Minimum deposit What it does
First deposit ever (locks tier) $50 Sets your permanent tier (Starter → Titan). Under $50 on the first credit → no promo ever, even on a $10,000 deposit later.
Pool unlock (Diamond / Elite / Titan after first deposit) $200 per top-up (Diamond & Elite); $2,000 per top-up (Titan) Releases the next $100 slice (Diamond/Elite) or $1,000 slice (Titan) from your locked pool. Must be within the 90-day vest window.
Titan 1% tail (after pool fully released) $500 per top-up Adds 1% bonus on each qualifying top-up for 90 days after the pool completes.

Prepay itself accepts deposits from $1 USDC upward (PREPAY_MIN_USDC). A $10 prepay credits balance but is not a qualifying promo deposit unless it satisfies the row that applies (e.g. $50+ on your very first credit).

Tier is chosen once

The first qualifying deposit (first credit ≥ $50) picks Starter / Growth / Pro / Diamond / Elite / Titan from that deposit’s dollar amount. Later deposits cannot upgrade the tier — they can only unlock remaining pool balance or earn Titan tail while those windows are active.

Preview before you send

GET /api/v1/balance/deposit/promo-preview?amount_usd=… with bearer shows estimated bonus for this agent (respects locked tier, prior deposits, and active pool/tail). Wallets that already made a first deposit do not see first-deposit bonus copy on /connect?action=topup.

Rules (authoritative)

  1. One promo per customer. The first qualifying deposit locks the tier permanently — later deposits cannot upgrade.
  2. Minimum $50 for any promo. First deposit below $50 → no promo ever, even on a $5,000 deposit later.
  3. Bonus is account credit for API usage only — not cash, not withdrawable.
  4. Anti-farming: one promotional grant promo per client; attempts to farm wallets may result in forfeiture of bonus credit.
  5. Applies to USDC prepay (POST /api/v1/balance/deposit/claim) and x402 top-up (POST /api/v1/balance/topup/x402).

Tier ladder

Tier First deposit Example total credit
Starter $50–$249 $50 → $62.50
Growth $250–$349 $250 → $325
Pro $350–$499 $350 → $500
Diamond $500+ $500 → $1,000*
Elite $1,000+ $1,000 → $2,000*
Titan $10,000+ $10,000 → $20,000 + 1% tail*

* Pool tiers: 30% upfront; remainder releases on qualifying follow-up top-ups (≥ $200 each for Diamond/Elite, ≥ $2,000 for Titan) within 90 days.
** Titan: 1% bonus on qualifying deposits (≥ $500 each) for 90 days after full pool release.

API

Human flow

  1. Open /promo — pick a tier, read the example line.
  2. CTA → /connect?action=topup&amount=250 (prefilled).
  3. Complete prepay; claim response includes promo_bonus_usd, promo_status.

Watcher deferral

Background deposit_watcher auto-credits linked wallets without client IP. Promo grant is pending until the agent hits any authenticated route that captures IP (typically /agents/me or manual deposit/claim).

See also