Vincent Hedera Allowance & Transfer Demo

This repository ships two packages:

• Backend (packages/backend) – Express API that validates Vincent-issued JWTs and executes the Vincent ERC‑20 allowance and ERC‑20 transfer abilities on Hedera testnet.
• Frontend (packages/frontend) – Vite/React UI that helps users mint Vincent JWTs, register delegates, and trigger allowance/transfer requests against the backend.

Every allowance/transfer request follows the same flow:

1. The frontend obtains a Vincent JWT for the user’s PKP (delegator) account and sends it to the backend.
2. The backend uses Lit Protocol’s delegate key to perform the requested action with your server-side signer—never the user’s private key.
3. The backend responds with Hedera transaction details (or reports when the allowance already satisfies the requirement).

Why Lit Protocol delegate keys matter

Lit’s Delegate Key infrastructure keeps the user experience fast while preserving self-custody. The user authorizes a single delegate (your backend) that is tightly scoped to Vincent abilities. The backend never handles the user’s private keys, but it can still create on-chain allowances or transfers the instant an authenticated request arrives. This unlocks:

• Granular permissions: delegates can only call the specific abilities you configure.
• Better latency: no wallet pop-ups once the delegate is approved, so recurring DCAs are seamless.
• Safety: revoking the delegate key immediately cuts off backend access without rotating the user’s wallet.

Requirements

• Node.js >=22.16.0 and pnpm >=9.15.0 (repo uses [email protected]).
• Access to a Hedera testnet RPC (Hashio is a good default).
• A Vincent app with abilities configured for USDC allowance + transfer.

Setup

1. Install dependencies once from the repo root; this wires up both backend and frontend workspaces:

   pnpm install

2. Copy the environment templates:

   cp packages/backend/.env.example packages/backend/.env
   cp packages/frontend/.env.example packages/frontend/.env

   • Backend variables are described below.
   • The frontend template simply mirrors your backend origin and Vincent app ID; open the file for inline notes.

Variable	Description
ALLOWED_AUDIENCE	Audience value your frontend JWT expects (typically the frontend origin)
CORS_ALLOWED_DOMAIN	Domain allowed to call this API in production
HEDERA_RPC_URL	RPC endpoint for Hedera testnet (e.g. https://testnet.hashio.io/api)
HEDERA_CHAIN_ID	EVM chain id for your Hedera network (defaults to 296)
HEDERA_USDC_TOKEN_ADDRESS	ERC-20 token contract to target (defaults to Hedera testnet USDC)
HEDERA_CHAIN_NAME	Lit-supported chain name for Hedera (defaults to hederaTestnet)
IS_DEVELOPMENT	Set true locally to allow any origin via CORS
PORT	Port for the Express server
VINCENT_APP_ID	Your Vincent app id (integer)
VINCENT_DELEGATEE_PRIVATE_KEY	Private key for the agent wallet that owns the Vincent abilities
SENTRY_DSN (optional)	Sentry DSN if you want error reporting

Running the packages

pnpm --filter backend dev     # Express API (tsx + dotenvx)
pnpm --filter frontend dev    # React client (Vite)

Both packages were installed when you ran pnpm install at the root. Build or start either package via pnpm --filter <name> build|start as needed.

Backend health lives at GET /health. Authenticated routes expect Authorization: Bearer <jwt> using a token issued by your Vincent app.

Method	Path	Description
GET	/auth/profile	Returns Vincent JWT details (requires Authorization header)
POST	/approve	Body { amount, spender, tokenAddress? } → returns { txHash?, alreadyApproved }
POST	/transfer	Body { amount, recipient, tokenAddress? } → returns { txHash, to, amount, tokenAddress, timestamp, precheck }

Prepare your Hedera testnet wallet

1. Create or log into the Hedera Developer Portal and generate an ECDSA testnet account.
2. Fund the account with testnet HBAR from the portal faucet.
3. Associate USDC token 0.0.429274 with the wallet. Most wallets have an “Associate Token” action where you paste the token ID, or you can run this Hedera Portal Script.
4. Visit the Circle testnet faucet, choose Hedera Testnet, enter your account ID, and request USDC. The facilitator will spend from this account when verifying payments; from there, you can transfer USDC to any delegate.

Fund the delegate account before use

When a user authorizes the Vincent delegate key, this backend mints a delegate account that will initiate allowances and transfers on their behalf. That delegate must have both HBAR and USDC before the API can succeed.

1. Copy the delegate account ID returned by your frontend when the PKP is created (or look it up in Hashscan from recent delegate registration transactions).
2. Send a few testnet HBAR to cover gas for future approvals/transfers.
3. Transfer the USDC you received from the Circle faucet to the delegate account. Any future allowance or transfer call will spend from this pool.
4. Optionally bookmark the account in your wallet so topping it up later is easy.

HBAR funding covers consensus and allowance transactions, while USDC is what Vincent spends against when scheduling DCA orders. Without both assets, the delegate transactions will revert.

Next steps

• Hit GET /health to confirm the server boots.
• Use the Vincent frontend to issue a JWT, then call /approve and /transfer to verify end-to-end.
• Monitor delegate balances in Hashscan to make sure HBAR + USDC stay topped up for production-like testing.