03 — Runtime Flows

The paths that matter, as they actually execute.

1. Sign in and obtain an API key

sequenceDiagram
    actor U as User
    participant T as Terminal
    participant A as Agent (SIWE)
    participant G as Gateway

    U->>T: Connect wallet
    T->>A: GET nonce
    A-->>T: nonce
    U->>T: Sign SIWE message
    T->>A: POST verify (message + signature)
    A->>A: Recover address, check token gate
    A-->>T: JWT (sub = wallet, access level)
    U->>T: "Create API key"
    T->>G: POST /keys  (Bearer JWT)
    G->>G: Verify JWT with shared secret
    G->>G: Generate hk_live_… , store SHA-256 hash only
    G-->>T: Plaintext key (returned exactly once)
    T-->>U: Copy-once dialog

The gateway and agent share JWT_SECRET_KEY, so one SIWE session works across both. Only the hash is stored — the plaintext cannot be recovered, which is why the UI must present a copy-once dialog.

2. Inference with an API key (the paid path)

sequenceDiagram
    participant C as Client (SDK/CLI/agent)
    participant G as Gateway
    participant P as Platform API
    participant V as vLLM cluster
    participant DB as Usage ledger

    C->>G: POST /v1/chat/completions (Bearer hk_live_…)
    G->>DB: Look up key by SHA-256 hash
    alt revoked or unknown
        G-->>C: 401
    end
    G->>P: GET /entitlements/{wallet}   (cached ~300s)
    P-->>G: {tier}
    alt tier < model.min_tier
        G-->>C: 403 (upgrade required)
    end
    G->>DB: Sum credits used this month
    alt quota exhausted
        G-->>C: 402 (buy overage / upgrade)
    end
    G->>V: Proxy request (upstream model id)
    V-->>G: Completion + usage
    G->>DB: Record prompt/completion tokens → credits
    G-->>C: Response (public model id)

Two deliberate properties: entitlement is cached but never trusted from the client, and metering happens after a successful response, so failed upstream calls are never billed.

3. Inference paid per call with x402 (the agent path)

sequenceDiagram
    participant A as External agent
    participant G as Gateway
    participant F as x402 facilitator
    participant V as vLLM cluster

    A->>G: POST /v1/chat/completions (no credentials)
    G-->>A: 402 + accepts[] (scheme, network, amount, payTo, asset)
    A->>A: Sign payment payload
    A->>G: Retry with X-PAYMENT header
    G->>F: POST /verify
    F-->>G: {isValid, payer}
    alt invalid
        G-->>A: 402 + reason
    end
    G->>V: Proxy request
    V-->>G: Completion
    G->>F: POST /settle
    F-->>G: {success, transaction}
    G-->>A: Response + X-PAYMENT-RESPONSE header

Verification precedes service and settlement follows it. A settlement that fails after the response has been sent is logged for reconciliation; exposure is bounded by the per-call price.

4. Gaining a tier on-chain

sequenceDiagram
    actor U as User
    participant T as Terminal
    participant TL as HunterTierLock (Base)
    participant W as Entitlement indexer [PLANNED]
    participant P as Platform API
    participant G as Gateway

    U->>T: Lock 10,000 DRPXBT for 90 days
    T->>TL: approve + lock(amount, duration)
    TL-->>TL: emit Locked(user, amount, start, end)
    W->>TL: Watch Locked/Unlocked/EarlyExit
    W->>TL: tierOf(user)
    W->>P: Upsert entitlement {wallet, tier, source, expires_at}
    G->>P: GET /entitlements/{wallet}
    P-->>G: {tier: 2}

Tier is derived from both amount and committed duration (end - start), so a large short lock does not buy a high tier. Reading tierOf is authoritative; the indexer only materialises it for fast lookup.

5. Autonomous signal pipeline

sequenceDiagram
    participant W as Workers (cron)
    participant AG as Agent pipeline
    participant M as MCP tools
    participant G as Gateway
    participant P as Platform API
    participant X as X / Telegram

    W->>AG: run_signal_pipeline(topic)
    AG->>M: search tweets, whale alerts, knowledge base
    M-->>AG: evidence
    AG->>G: research / draft / critique completions
    loop until APPROVE (bounded revisions)
        AG->>G: critique draft
    end
    AG-->>W: {draft, approved, editor verdict}
    alt approved
        W->>P: POST /api/v1/signals (external_id, asset, direction, thesis)
        W->>X: Publish (human-gated initially)
    end
    Note over W,P: later — scorer resolves the outcome
    W->>P: POST /api/v1/signals/{id}/outcome {verdict, price_change_pct}

Every published call is recorded before the outcome is known, which is what makes the public scoreboard credible — we cannot retroactively drop losers.

6. Agent-to-agent commerce (ACP)

sequenceDiagram
    participant B as Buyer agent
    participant ACP as Virtuals ACP (Base)
    participant W as ACP worker [PLANNED]
    participant AG as Agent /acp/jobs
    participant S as Revenue splitter

    B->>ACP: Request "research_report" (priced, escrowed)
    ACP-->>W: Job assigned
    W->>AG: POST /acp/jobs {service_id, params, job_id} (X-ACP-Token)
    AG->>AG: Execute pipeline (tools + gateway)
    AG-->>W: Deliverable (markdown report)
    W->>ACP: Submit deliverable
    ACP->>S: Release escrow → revenue

The seller-side execution API is built and tested today; the on-chain listener is the remaining piece.

7. Revenue → buyback → burn

[PLANNED] — the contracts below are not deployed; this is the designed flow, not current behaviour.

sequenceDiagram
    participant SRC as Revenue sources
    participant SP as HunterRevenueSplitter
    participant BB as HunterBuyback
    participant DEX as Uniswap v3 (Base)
    participant ST as HunterStaking
    participant TR as Treasury multisig
    participant K as Keeper

    SRC->>SP: USDC (subscriptions, overage, x402, ACP)
    K->>SP: distribute(USDC)
    SP->>BB: 40%
    SP->>ST: 30% (notifyRewardAmount → streams to stakers)
    SP->>TR: 30%
    K->>BB: buybackAndBurn(USDC, amount, minOut, fee)
    BB->>DEX: exactInputSingle → DRPXBT
    DEX->>BB: DRPXBT sent to 0x…dEaD

Buybacks are clip-bounded and rate-limited on-chain (maxClipSize, minClipInterval) with an off-chain TWAP-derived minAmountOut, so a keeper key cannot dump the treasury into a thin market in one transaction.

8. Public proof (the flywheel dashboard)

[PLANNED] — the dashboard is built, but reads contracts that are not yet deployed, so it renders in pre-launch mode.

sequenceDiagram
    participant V as Visitor
    participant S as drpxbt.xyz /flywheel
    participant B as Base RPC

    V->>S: Load page
    par Parallel eth_call
        S->>B: balanceOf(0x…dEaD) on DRPXBT
        S->>B: totalSupply() on DRPXBT
        S->>B: totalLocked() on TierLock
        S->>B: totalSupply() on Staking
    end
    B-->>S: raw uint256 values
    S->>S: Format, compute % off market
    S-->>V: Live stats + Basescan links

No backend involved: the page reads the chain directly, so the numbers cannot be massaged by our infrastructure. That is the entire point.