> ## Documentation Index
> Fetch the complete documentation index at: https://hevninc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```http theme={null}
GET /mcp/get_balance
```

CLI surface:

```bash theme={null}
hevn balance
```

Purpose:

* returns the MCP wallet email,
* returns the MCP wallet address,
* returns USDC balance,
* returns remaining allowance.

## API-key introspection

```http theme={null}
GET /apps/me
```

CLI surface:

```bash theme={null}
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

```http theme={null}
POST /apps/transfer
```

CLI surfaces:

```bash theme={null}
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:

```http theme={null}
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:

```json theme={null}
{
  "invoiceId": "inv_123",
  "memo": "Invoice payment"
}
```

Contact transfer payload:

```json theme={null}
{
  "contactId": "contact_123",
  "amount": 25,
  "memo": "Thanks"
}
```

Payout quote transfer payload:

```json theme={null}
{
  "quoteId": "quote_123",
  "memo": "Bank payout"
}
```

At least one of `contactId`, `invoiceId`, or `quoteId` is required.

## Transfer history

```http theme={null}
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:

```http theme={null}
GET /apps/transfers?limit=50&offset=0&idempotency_key=op_123
```

<Note>
  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.
</Note>

## 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`.