MCP API

App-scoped transfer endpoints used by HEVN CLI balance and transfer commands.

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 [e-mail] 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:

Parameter	Type	Purpose
limit	integer	Maximum number of transfers to return.
offset	integer	Pagination offset.
idempotency_key	string	Filter 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.