Hermes Bank technical map.

Quickstart

The current site includes a working mock Hermes API. It demonstrates the user journey, dashboard states, card tabs, balances, transaction ledger, and agent-facing card issue endpoint. Production requires persistent database storage, real crypto confirmation, and provider fulfillment credentials.

Local site:
http://localhost:4174

Production:
https://hermes-bank-site.vercel.app

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

Working API 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"
}

In production, sensitive card delivery fields should be encrypted at rest and only revealed after user authentication. The dashboard should show exactly what the provider returns: 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. GET /agent-manifest.json
2. Read required scopes and policy defaults.
3. GET /api/balances before requesting spend.
4. POST /api/payment-intents with idempotency key.
5. POST /api/agent-card-issue after payment confirmation.
6. 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.

API Reference

The public frontend and agents should use Hermes endpoints only. These routes are implemented in mock mode now and should keep the same response shape when the production backend is connected.

POST /api/payment-intents
Create a crypto checkout request.

GET /api/balances
Return current dashboard balances.

POST /api/agent-card-issue
Create a prepaid card order after confirmed payment.

GET /api/cards
List issued card tabs for the authenticated user.

GET /api/cards/:id
Return one card and its revealable delivery fields.

GET /api/transactions
Return ledger events for dashboard table.

POST /api/agent-card-issue
{
  "agentId": "ops-agent-02",
  "mission": "buy API credits",
  "cardType": "Hermes Prepaid Visa",
  "country": "US",
  "amount": 50,
  "recipientLabel": "Ops Agent"
}

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. Integrate Reloadly sandbox for product discovery and orders.
4. Add secure card reveal flow with encrypted storage.
5. Ship admin reconciliation for failed orders and refunds.
6. Move from demo dashboard to authenticated user accounts.