# Payments & HITL gate

LoopDesk's payment surfaces are powered by [**Agent Passport**](https://agentpassport.ai) (by GoKite AI) — payments infrastructure purpose-built for agentic workflows. Agent Passport gives every agent a verifiable identity, rule-bound spending authority, and stablecoin rails with instant settlement, so AI agents can transact within bounds you define. LoopDesk layers human oversight on top: the same routing policy that governs the review queue also governs which payments execute automatically and which require a human signature.

The `/payments` routes are additionally gated by a $HITL token balance check on top of standard wallet auth — a programmable access control for sensitive surfaces.

## Why Agent Passport

Traditional payment processors assume a human is clicking "pay". Agent Passport is built for the case where an AI agent is the initiator. It provides:

* **A secure identity per agent** — each agent gets a verifiable passport rather than sharing a single API key
* **Rule-bound authority** — per-transaction caps, daily limits, recipient whitelists, session expiry
* **Stablecoin rails** — micro-payments and high-volume agentic spending without per-transaction overhead
* **Human-approval hooks** — high-value or out-of-policy transactions route to a human before settlement

That last property is where LoopDesk fits. Agent Passport defines *what an agent is allowed to do*; LoopDesk's HITL queue handles *the cases where the agent's intent needs human confirmation*.

## How the integration works

```
┌──────────────┐  intent   ┌──────────────────┐   policy check    ┌─────────────────┐
│  Your agent  │ ────────► │  Agent Passport  │ ────────────────► │  Within bounds  │ ──► settled
└──────────────┘           │  (GoKite AI)     │                   └─────────────────┘
                           │                  │
                           │                  │   out-of-policy   ┌─────────────────┐
                           │                  │ ────────────────► │ LoopDesk queue  │ ──► human approves ──► settled
                           └──────────────────┘                   └─────────────────┘
```

1. Your agent expresses payment intent (recipient, amount, context).
2. Agent Passport evaluates it against the configured rules (per-tx cap, daily budget, whitelist, session validity).
3. **In-policy:** Agent Passport executes the payment on stablecoin rails and returns a settlement receipt.
4. **Out-of-policy or flagged:** the intent is submitted to LoopDesk as an item with `risk_flags: ["payment", "high_value", ...]`. A human reviewer approves, edits, or rejects in the queue. On approval, LoopDesk's outbound webhook signals Agent Passport to settle.

## How the $HITL gate works

`src/components/HitlGate.tsx` wraps payment routes. On mount it:

1. Reads the connected wallet from the Solana provider context
2. Calls `useHitlBalance()` to fetch the wallet's $HITL token balance
3. Compares against `MIN_HITL_BALANCE` from `src/lib/hitl/config.ts`
4. Renders children only when the balance meets the minimum

If the balance is below the threshold, the user sees a prompt explaining what $HITL is and how to acquire it. The client-side gate is for UX; server-side, payment actions re-verify the balance before any Agent Passport call. See `src/lib/hitl/link.functions.ts`.

## Why a token gate

Payment routes can move real value. Gating on a token balance:

* **Prevents drive-by abuse** — random wallets can't even see the payment UI
* **Aligns access with skin-in-the-game holders**
* **Provides a programmable knob** — raise/lower the threshold without redeploying
* **Sits orthogonal to identity** — the wallet balance is the access credential; user identity lives in `profiles`

It is not a substitute for authentication, role-based access, or Agent Passport's own per-transaction policy. It is one extra layer on a route that warrants extra layers.

## Policy

LoopDesk's local policy (`src/lib/payments/policy.ts`) is consulted before every Agent Passport call. It encodes per-transaction caps, daily budgets, and the threshold above which a payment must route through the HITL queue regardless of Agent Passport's own rules:

```ts
const ok = await checkPaymentPolicy({
  walletAddress,
  amount,
  recipient,
  context,
});
if (!ok.allowed) {
  return { error: ok.reason };
}
```

Policy violations don't outright reject. They route the payment through the standard HITL queue with `risk_flags: ["high_value", "payment"]` — a human reviewer makes the final call, and on approval the action is dispatched to Agent Passport.

## Configuration

| Constant             | Where                        | Purpose                                  |
| -------------------- | ---------------------------- | ---------------------------------------- |
| `MIN_HITL_BALANCE`   | `src/lib/hitl/config.ts`     | Minimum $HITL to access /payments        |
| `HITL_TOKEN_MINT`    | `src/lib/hitl/config.ts`     | SPL token mint address                   |
| `PAYMENT_DAILY_CAP`  | `src/lib/payments/policy.ts` | Per-wallet daily ceiling                 |
| `PAYMENT_AUTO_LIMIT` | `src/lib/payments/policy.ts` | Single payment above this routes to HITL |
| Agent Passport rules | Agent Passport dashboard     | Per-agent caps, whitelist, session TTL   |

## Source files

* `src/components/HitlGate.tsx` — client-side $HITL gate
* `src/lib/hitl/use-hitl-balance.ts` — balance hook
* `src/lib/hitl/link.functions.ts` — server-side verification
* `src/lib/payments/policy.ts` — local payment policy
* `src/lib/payments/provider.ts` — Agent Passport integration
* `src/routes/_app/payments.tsx`, `payments.new.tsx` — gated routes

## Further reading

* [Agent Passport](https://agentpassport.ai) — product overview
* [GoKite AI documentation](https://docs.gokite.ai/) — protocol spec, SDKs, agent identity model


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hitl-01.gitbook.io/hitl-docs/features/payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.