Skip to main content
McpApi reuses the same configured HEVN API key as the rest of the CLI. Transfer endpoints no longer require an app id; the backend resolves the owning app from the calling API key.

​
Balance

GET /mcp/get_balance
CLI surface: 
hevn balance
Purpose:
  • returns the MCP wallet email,
  • returns the MCP wallet address,
  • returns USDC balance,
  • returns remaining allowance.

​
API-key introspection

GET /apps/me
CLI surface: 
hevn whoami
Purpose:
  • returns the user name and email,
  • returns the owning app id and app name,
  • returns granted API-key scopes,
  • returns balance and remaining spend limit.

​
Submit transfer

POST /apps/transfer
CLI surfaces: 
hevn transfer --invoice-id <invoice-id>
hevn transfer email vendor@example.com 25
hevn transfer contact <contact-id> 25
hevn transfer contact --contact-id <contact-id> --quote-id <quote-id>
Headers: 
Authorization: Bearer hvn_...
Accept: application/json
Idempotency-Key: <optional-stable-operation-id>
If the CLI is configured with HEVN_API_KEY_HEADER=X-Api-Key, the same request uses X-Api-Key: hvn_... instead. Invoice transfer payload: 
{
  "invoiceId": "inv_123",
  "memo": "Invoice payment"
}
Contact transfer payload: 
{
  "contactId": "contact_123",
  "amount": 25,
  "memo": "Thanks"
}
Payout quote transfer payload: 
{
  "quoteId": "quote_123",
  "memo": "Bank payout"
}
At least one of contactId, invoiceId, or quoteId is required.

​
Transfer history

GET /apps/transfers
Query parameters:
ParameterTypePurpose
limitintegerMaximum number of transfers to return.
offsetintegerPagination offset.
idempotency_keystringFilter or look up by idempotency key.
Example: 
GET /apps/transfers?limit=50&offset=0&idempotency_key=op_123
The current CLI exposes transaction history through hevn transfer list, which uses the app /transactions endpoint. The MCP transfer history wrapper exists in McpApi for direct internal use.

​
Legacy routes

Older API specs exposed POST /apps/{app_id}/transfer. The current CLI does not call that route and does not read HEVN_APP_ID.