Hermes Bank technical map.

Quickstart

Hermes Bank gives users and agents a controlled prepaid card surface. The dashboard handles card creation, balance visibility, card tabs, transaction history, and agent-facing card requests.

Local site:
http://localhost:4174

Production:
https://hermesbank.one

Core pages:
/          marketing page
/dashboard prepaid card desk
/agent     agent wrapper
/docs      technical documentation

Hermes endpoints:
/api/balances
/api/cards
/api/transactions
/api/payment-intents
/api/agent-card-issue

Architecture

Hermes should be structured as a thin product layer over three secure systems: crypto checkout, prepaid fulfillment, and internal ledger. The user should never see raw provider implementation details. The dashboard should only show Hermes-branded cards, balances, orders, and transaction state.

1. User chooses card type, country, amount, and recipient label.
2. Backend creates a crypto payment intent with amount plus fee.
3. Crypto watcher confirms payment on the selected network.
4. Backend creates the prepaid card order through fulfillment rails.
5. Backend stores card metadata and encrypted card delivery data.
6. Dashboard reads cards, balances, and transactions from Hermes API.

Browser
  -> Hermes API
    -> Crypto payment service
    -> Ledger database
    -> Prepaid fulfillment provider
  -> Dashboard card tab + transaction ledger

Dashboard

The dashboard is the operating console. It should answer four questions immediately: how much spend is available, what cards exist, what was paid, and what is waiting for settlement.

Card Issuance

A card should be created only after confirmed payment. The card tab is the delivery surface: it contains the Hermes card artwork on one side and returned card data on the other side.

{
  "type": "Hermes Prepaid Visa",
  "country": "US",
  "amount": 50,
  "recipient": "Research Agent",
  "status": "DELIVERED",
  "orderId": "ORD-8K2DP-N4M9Q",
  "issuedAt": "2026-06-21T19:35:00.000Z"
}

Sensitive card delivery fields are treated as private card data. The dashboard reveals only the fields required for the user or agent mission: card code, PIN, redemption URL, expiry, or instructions depending on product type.

Transactions

Every user-visible card should map to ledger events. At minimum, each card order creates a crypto payment transaction and a prepaid order transaction. Later versions should add refunds, failed orders, settlement adjustments, and manual review events.

{
  "id": "tx_01J...",
  "type": "Crypto payment",
  "status": "CONFIRMED",
  "amount": 51.50,
  "asset": "USDC",
  "reference": "PAY-2K4M9-Q8W7P",
  "createdAt": "2026-06-21T19:35:00.000Z"
}

Balances

Balances must be derived from the ledger, not manually edited in the browser. The frontend should call a backend balance endpoint that returns the latest available crypto balance, fulfillment reserve, pending spend, and issued volume.

{
  "cryptoBalance": {
    "asset": "USDC",
    "available": 2788.50
  },
  "fulfillmentBalance": {
    "currency": "USD",
    "available": 1870.00
  },
  "issuedVolume": 50.00,
  "pendingSpend": 0.00,
  "updatedAt": "2026-06-21T19:35:00.000Z"
}

Agent Shell

The Agent Shell is the machine-facing wrapper around Hermes. It is designed for AI agents that need to discover allowed payment actions, request permissioned prepaid cards, and read ledger state without receiving owner wallet access.

Agent startup flow:
1. Read assigned policy and spend scope.
2. GET /api/balances before requesting spend.
3. POST /api/payment-intents with idempotency key.
4. POST /api/agent-card-issue after payment confirmation.
5. GET /api/transactions to reconcile the mission ledger.

Required scopes:
balances:read
transactions:read
cards:issue
cards:read

Reloadly Rail

Reloadly can be used as the prepaid fulfillment layer. Its tokens are product-scoped, so the backend should request the correct audience for the product being used. Keep Reloadly credentials and product metadata server-side only.

Auth:
POST https://auth.reloadly.com/oauth/token
grant_type=client_credentials
audience=https://giftcards.reloadly.com

Sandbox base:
https://giftcards-sandbox.reloadly.com

Production base:
https://giftcards.reloadly.com

Fulfillment flow:
1. GET products and validate country/amount availability.
2. POST /orders after crypto payment confirmation.
3. Store provider transaction ID internally.
4. GET /orders/transactions/{transactionId}/cards.
5. Return Hermes-formatted card details to dashboard.

Security and Risk Rules

• Never create a card order before crypto confirmation.
• Encrypt card delivery data at rest.
• Do not log full card codes, PINs, redemption URLs, or secrets.
• Apply per-user, per-agent, and per-day issuance limits.
• Block unsupported countries before checkout.
• Require manual review for repeated failed payments or high velocity.
• Keep provider API keys in server environment variables only.
• Use idempotency keys for payment and card order creation.

Product Copy Rules

Hermes should sound private, premium, and operational. Avoid claiming regulated banking functionality until the legal and issuing partner setup exists. The product promise is controlled prepaid spend for agents, not a full bank account.

Roadmap

1. Connect real crypto payment intents and confirmation webhooks.
2. Add database-backed balances, cards, users, and transactions.
3. Expand fulfillment coverage across supported prepaid products.
4. Add secure card reveal flow with encrypted storage.
5. Ship admin reconciliation for failed orders and refunds.
6. Expand authenticated user and agent account controls.