# Agent workflows
Source: https://hevninc.mintlify.app/agent-workflows

Primary operating guide for AI agents and scripts that use HEVN CLI safely.

HEVN CLI is designed primarily for AI agents and automation, with human terminal output as a convenience layer. Agents should prefer explicit flags, structured output, non-interactive execution, and confirmation-free commands only when the user's intent is clear.

<Note>
  Using an MCP coding agent like Claude Code, Codex, or Cursor? Run [`hevn mcp install`](/connect-agents) to expose every command as an MCP tool — the guidance below is delivered to the agent automatically.
</Note>

## Discover the CLI contract

Before planning or executing a HEVN workflow, load the packaged agent guide:

```bash theme={null}
hevn agent-skill
```

This command prints the current `CLAUDE.md` operating guide shipped with the CLI. Agents must read it first because it contains workflow-specific instructions that are more detailed than the command manifest.

Then load the machine-readable manifest:

```bash theme={null}
hevn --schema
```

The schema includes commands, global options, auth methods, output envelopes, danger levels, idempotency support, and stable error codes.

## Use structured output

Prefer YAML or JSON for reads and automation. In structured mode, successful output is wrapped in `ok`, `data`, `meta`, and `warnings`; errors include `errorCode`, `errorType`, `error`, and `exitCode`.

```bash theme={null}
hevn --yaml whoami
hevn profile get --yaml
hevn contacts list --yaml
hevn contracts preview --id <contract-id> --yaml
```

Use `--non-interactive` or `--no-input` when prompts must be forbidden:

```bash theme={null}
hevn --non-interactive --yaml contacts list
```

## Read before writing

For money movement and contract operations, load the relevant resource first:

```bash theme={null}
hevn profile get --yaml
hevn contacts list --yaml
hevn invoice get <invoice-id> --yaml
hevn contracts preview --id <contract-id> --yaml
```

Then perform the write with explicit ids and amounts.

## Contract role selection

When creating a contract from a document, determine which party is the current HEVN user:

```bash theme={null}
hevn profile get --yaml
```

Then compare the current user against the parties in the document.

* If the current user is the client, pass the counterparty as `--contractor-email`.
* If the current user is the contractor, pass the counterparty as `--client-email`.

The email flag always identifies the counterparty's role, not the current user's role.

<Warning>
  Do not assume the current HEVN user is always the client. Many contract workflows have the current user acting as the contractor.
</Warning>

## Avoid invented data

If a document does not contain the counterparty's email, ask the user. Do not invent emails, addresses, tax ids, bank details, invoice dates, or amounts.

## Use idempotency for transfers

For payment automation, pass your own idempotency key:

```bash theme={null}
hevn transfer contact \
  --contact-id <contact-id> \
  --amount 25 \
  --idempotency-key <stable-operation-id> \
  --yaml
```

Use `--dry-run` for mutating commands when you need to inspect the would-be request before sending it:

```bash theme={null}
hevn --dry-run transfer --invoice-id <invoice-id> --memo "Invoice payment"
```

## Confirmation flags

Use `--yes` only when the user or upstream workflow has already approved the action:

```bash theme={null}
hevn transfer contact --contact-id <contact-id> --amount 25 --yes
hevn invoice decline --invoice-id <invoice-id> --yes
hevn contracts delete --id <contract-id> --yes
```

## Debug safely

`--debug` can include curl commands and authentication details. Use it for local troubleshooting, but redact before storing or sharing logs.


# App API
Source: https://hevninc.mintlify.app/api-reference/app-api

Authenticated REST endpoints used by HEVN CLI AppApi.

`AppApi` uses app authentication. See [Authentication](/api-reference/authentication) for header details.

## Account and profile

| Method | Endpoint           | CLI surface                            | Purpose                                |
| ------ | ------------------ | -------------------------------------- | -------------------------------------- |
| `GET`  | `/user`            | `hevn account get`, `hevn profile get` | Load the current user profile.         |
| `PUT`  | `/user/kyc`        | `hevn profile set`                     | Update profile and KYC profile fields. |
| `POST` | `/user/kyc_link`   | `hevn account kyc`                     | Create or fetch a KYC link.            |
| `GET`  | `/user/kyc/status` | `hevn account kyc --status`            | Fetch KYC status for a provider.       |
| `GET`  | `/balance`         | `hevn account list`                    | Fetch app balance accounts.            |

KYC status query:

```http theme={null}
GET /user/kyc/status?provider=swipelux
```

<Note>
  KYB endpoints are available in the generated OpenAPI reference for direct REST integrations. The CLI does not currently expose a dedicated KYB command flow.
</Note>

Profile update example:

```json theme={null}
{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "entityName": "Example Ltd",
  "address": {
    "streetAddress": "1 Example Street",
    "city": "London",
    "country": "GB",
    "zip": "SW1A1AA"
  }
}
```

## Contacts

| Method   | Endpoint                      | CLI surface                          | Purpose                        |
| -------- | ----------------------------- | ------------------------------------ | ------------------------------ |
| `GET`    | `/user/contacts`              | `hevn contacts list`                 | List contacts.                 |
| `POST`   | `/user/contact`               | `hevn contacts new`                  | Create a contact.              |
| `PATCH`  | `/user/contacts/{contact_id}` | `hevn contacts new --contact-id ...` | Update contact metadata.       |
| `DELETE` | `/user/contacts/{contact_id}` | `hevn contacts delete`               | Delete a contact.              |
| `POST`   | `/user/contact/bank/validate` | `hevn banks validate`                | Validate bank account details. |

List contacts query:

```http theme={null}
GET /user/contacts?limit=100&offset=0
```

Email contact payload:

```json theme={null}
{
  "name": "Vendor",
  "relationship": "external",
  "account": {
    "accountType": "email",
    "email": "vendor@example.com"
  }
}
```

On-chain contact payload:

```json theme={null}
{
  "name": "Treasury wallet",
  "relationship": "external",
  "account": {
    "accountType": "onchain",
    "email": "owner@example.com",
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "chainId": "base",
    "currency": "USDC"
  }
}
```

Bank validation payload:

```json theme={null}
{
  "bankType": "sepa",
  "country": "DE",
  "bankName": "Example Bank",
  "iban": "DE89370400440532013000",
  "bic": "DEUTDEFF",
  "routingNumber": null
}
```

## Documents

| Method | Endpoint            | CLI surface                                                          | Purpose                                 |
| ------ | ------------------- | -------------------------------------------------------------------- | --------------------------------------- |
| `POST` | `/documents/upload` | `hevn invoice upload-incoming`, `hevn contracts new --document-path` | Upload an invoice or contract document. |

Document upload payload:

```json theme={null}
{
  "base64": "<base64-document-bytes>",
  "type": "invoice",
  "name": "invoice",
  "originName": "invoice.pdf",
  "context": "invoice"
}
```

For contracts, the CLI sends `type: "contract"` and `context: "contract"`.

## Invoices

| Method | Endpoint                                            | CLI surface                       | Purpose                                      |
| ------ | --------------------------------------------------- | --------------------------------- | -------------------------------------------- |
| `GET`  | `/documents/contracts/invoices`                     | `hevn invoice list`, `hevn bills` | List invoices.                               |
| `GET`  | `/documents/contracts/invoices/{invoice_id}`        | `hevn invoice get`                | Fetch invoice details.                       |
| `POST` | `/documents/contracts/invoices`                     | `hevn invoice new`                | Create an invoice.                           |
| `POST` | `/documents/contracts/invoices/uploaded`            | `hevn invoice upload-incoming`    | Create an invoice from an uploaded document. |
| `PUT`  | `/documents/contracts/invoices/{invoice_id}`        | `hevn invoice decline`            | Update invoice state.                        |
| `POST` | `/documents/contracts/{contract_id}/create-invoice` | `hevn invoice new --contract-id`  | Create an invoice from a contract.           |
| `POST` | `/documents/contracts/invoices/batch_invoicing`     | `hevn invoice batch`              | Generate invoices for multiple contracts.    |

Create invoice payload example:

```json theme={null}
{
  "currency": "USD",
  "contractorEmail": "vendor@example.com",
  "contractorDisplayName": "Vendor",
  "clientEmail": "client@example.com",
  "clientDisplayName": "Client Company",
  "clientAddress": {
    "streetAddress": "1 Example Street",
    "city": "London",
    "country": "GB",
    "zip": "SW1A1AA"
  },
  "items": [
    {
      "name": "Consulting",
      "quantity": 1,
      "price": 100
    }
  ],
  "invoicePrefix": "INV",
  "onchain": true,
  "dueDate": "2026-06-01"
}
```

Create from contract payload example:

```json theme={null}
{
  "contractorAddress": {
    "streetAddress": "1 Example Street",
    "city": "London",
    "country": "GB",
    "zip": "SW1A1AA"
  },
  "invoicePrefix": "INV",
  "periodStart": "2026-06-01",
  "addItems": [
    {
      "name": "Extra support",
      "quantity": 1,
      "price": 250
    }
  ]
}
```

Batch invoicing payload:

```json theme={null}
[
  {
    "contractId": "contract_123",
    "period": 0,
    "memo": "May payroll",
    "items": [
      {
        "name": "Monthly services",
        "quantity": 1,
        "price": "5000"
      }
    ]
  }
]
```

## Contracts

| Method   | Endpoint                                             | CLI surface                                                  | Purpose                                             |
| -------- | ---------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
| `GET`    | `/documents/contracts`                               | `hevn contracts list`, `hevn contractors list`               | List contracts.                                     |
| `GET`    | `/documents/contracts/{contract_id}`                 | `hevn contracts get`                                         | Fetch a contract.                                   |
| `GET`    | `/documents/contracts/{contract_id}/preview`         | `hevn contracts preview`                                     | Preview resolved contract fields and document text. |
| `GET`    | `/documents/contracts/templates`                     | `hevn contracts generate`, `hevn hire`                       | List available contract templates.                  |
| `POST`   | `/documents/contracts`                               | `hevn contracts new`, `hevn contracts generate`, `hevn hire` | Create a contract.                                  |
| `PATCH`  | `/documents/contracts/{contract_id}`                 | `hevn contracts update`                                      | Update contract fields and schedule.                |
| `POST`   | `/documents/contracts/{contract_id}/pause`           | `hevn contracts pause`                                       | Pause a contract.                                   |
| `POST`   | `/documents/contracts/{contract_id}/approve`         | `hevn contracts approve`                                     | Approve a contract.                                 |
| `PUT`    | `/documents/contracts/{contract_id}/payment_methods` | `hevn contracts payment-methods`                             | Replace contract payment methods.                   |
| `DELETE` | `/documents/contracts/{contract_id}`                 | `hevn contracts delete`                                      | Delete a contract.                                  |

Create contract payload example:

```json theme={null}
{
  "contractorEmail": "contractor@example.com",
  "type": "default_contractor",
  "fields": {
    "amount": "5000",
    "currency": "USD",
    "jobTitle": "Engineer",
    "scopeDescription": "Full-time engineering work"
  },
  "period": "monthly",
  "activationAt": "2026-05-01T00:00:00Z",
  "label": "contractor@example.com - Contractor Agreement",
  "priorityMethods": ["internal"],
  "requireSignature": false
}
```

Payment methods payload:

```json theme={null}
{
  "paymentMethods": [
    {
      "accountType": "email",
      "email": "contractor@example.com"
    }
  ]
}
```

## Transactions

| Method | Endpoint        | CLI surface                                   | Purpose            |
| ------ | --------------- | --------------------------------------------- | ------------------ |
| `GET`  | `/transactions` | `hevn transfer list`, `hevn pending-deposits` | List transactions. |

Transaction query parameters used by the CLI:

```http theme={null}
GET /transactions?limit=50&offset=0&type=ach,fedwire&status=pending&incomeOnly=true&bankAccountId=bank_123
```

## Banks and quotes

| Method | Endpoint                    | CLI surface                               | Purpose                         |
| ------ | --------------------------- | ----------------------------------------- | ------------------------------- |
| `GET`  | `/banks`                    | `hevn banks list`, bank payout selection  | List banks and available rails. |
| `POST` | `/banks/activate`           | Bank payout flow                          | Activate bank rails.            |
| `POST` | `/balance/payin/quote`      | `hevn deposit`                            | Create crypto deposit quote.    |
| `POST` | `/banks/payin/quote`        | `hevn deposit --from bank`                | Create bank pay-in quote.       |
| `POST` | `/banks/payin/quote/submit` | `hevn deposit --from bank`                | Submit bank pay-in quote.       |
| `POST` | `/balance/payout/quote`     | `hevn transfer contact` for bank contacts | Create payout quote.            |

Pay-in quote payload:

```json theme={null}
{
  "amount": 100,
  "currency": "USDC",
  "originChainId": "base"
}
```

Bank pay-in quote payload:

```json theme={null}
{
  "amount": 100,
  "bankAccountId": "bank_123",
  "memo": "Funding treasury"
}
```

Payout quote payload:

```json theme={null}
{
  "contactId": "contact_123",
  "amount": 25,
  "bankAccountId": "bank_123"
}
```

## Cards

| Method | Endpoint                    | CLI surface                                | Purpose                                       |
| ------ | --------------------------- | ------------------------------------------ | --------------------------------------------- |
| `GET`  | `/cards`                    | `hevn cards list`, `hevn cards status`     | List cards and card readiness state.          |
| `POST` | `/cards`                    | Hidden `hevn cards issue`                  | Create a card.                                |
| `GET`  | `/cards/{card_id}`          | Card-specific internal wrapper             | Fetch a card.                                 |
| `POST` | `/cards/{card_id}/details`  | Card-specific internal wrapper             | Request card details.                         |
| `PUT`  | `/cards/{card_id}/label`    | Card-specific internal wrapper             | Update card label.                            |
| `PUT`  | `/cards/{card_id}/limit`    | Card-specific internal wrapper             | Update card limit.                            |
| `POST` | `/cards/{card_id}/freeze`   | Card-specific internal wrapper             | Freeze a card.                                |
| `POST` | `/cards/{card_id}/unfreeze` | Card-specific internal wrapper             | Unfreeze a card.                              |
| `POST` | `/cards/kyc/link`           | `hevn cards kyc-link`                      | Create or fetch card KYC link.                |
| `POST` | `/cards/pre-approve`        | Card list KYC prompt, hidden `pre-approve` | Prepare card KYC or check card prerequisites. |

Create card payload:

```json theme={null}
{
  "format": "virtual"
}
```

Update label payload:

```json theme={null}
{
  "label": "Team card"
}
```


# Introspect the current API key
Source: https://hevninc.mintlify.app/api-reference/apps/introspect-the-current-api-key

/openapi.json get /api/v1/apps/me
Return the user identity, owning app, granted scopes, balance, and remaining spend limit for the configured API key. Used by `hevn whoami`.



# List transfers for the app resolved by the API key
Source: https://hevninc.mintlify.app/api-reference/apps/list-transfers-for-the-app-resolved-by-the-api-key

/openapi.json get /api/v1/apps/transfers
List app-scoped transfers for the app associated with the calling API key. This is the app-id-free transfer history route used by the current HEVN CLI wrapper.



# Send USDC from the app resolved by the API key
Source: https://hevninc.mintlify.app/api-reference/apps/send-usdc-from-the-app-resolved-by-the-api-key

/openapi.json post /api/v1/apps/transfer
Resolve recipient and amount from context, then spend USDC through the app associated with the calling API key. This is the app-id-free transfer route used by the current HEVN CLI.



# Authentication
Source: https://hevninc.mintlify.app/api-reference/authentication

Authentication modes and headers used by HEVN CLI REST calls.

The CLI uses one HEVN API key for authenticated app and transfer endpoints, plus a public mode for unauthenticated reads.

## HEVN API key mode

Authenticated endpoints build headers from `HEVN_API_KEY` or saved login config.

Default header:

```http theme={null}
Authorization: Bearer hvn_...
Accept: application/json
device-id: hevn-cli
device-type: cli
device-name: HEVN CLI
```

Set it manually:

```bash theme={null}
export HEVN_API_KEY="hvn_..."
# Optional. Defaults to Authorization.
export HEVN_API_KEY_HEADER="Authorization"
```

Use browser login:

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

or direct API-key login for automation:

```bash theme={null}
hevn login --api-key hvn_...
hevn login --api-key hvn_... --api-key-header X-Api-Key
```

`hevn login` stores the API key, header mode, and optional base URL in the local CLI config.

## Alternate X-Api-Key mode

Some deployments require `X-Api-Key` instead of `Authorization`:

```bash theme={null}
export HEVN_API_KEY="hvn_..."
export HEVN_API_KEY_HEADER="X-Api-Key"
```

The CLI reuses whichever header was configured for all authenticated endpoints, including transfers.

## Non-interactive auth

In CI and other non-interactive environments, avoid browser login and pass a key directly:

```bash theme={null}
hevn login --api-key hvn_...
HEVN_API_KEY=hvn_... hevn whoami --yaml
```

If interactive login is attempted in non-interactive mode, the CLI exits with `AUTH_REQUIRED` and reports the supported auth methods.

## Idempotency

Transfer and deposit writes can include:

```http theme={null}
Idempotency-Key: <stable-operation-id>
```

CLI example:

```bash theme={null}
hevn transfer contact \
  --contact-id <contact-id> \
  --amount 25 \
  --idempotency-key <stable-operation-id>
```

## API-key introspection

Use `whoami` to inspect the active API key, owning app, scopes, balance, and remaining spend limit:

```bash theme={null}
hevn whoami --yaml
```

## Public mode

`PublicApi` sends only:

```http theme={null}
Accept: application/json
```

It is used for FX rates and public invoice lookup.

<Warning>
  Debug output may include authentication headers. Redact debug logs before sharing them.
</Warning>


# Get KYB draft
Source: https://hevninc.mintlify.app/api-reference/b2b/get-kyb-draft

/openapi.json get /api/v1/kyb/b2b/kyb/draft
Get current KYB draft with all data and signed URLs for documents.



# Request KYB for a provider
Source: https://hevninc.mintlify.app/api-reference/b2b/request-kyb-for-a-provider

/openapi.json post /api/v1/kyb/b2b/kyb/request
Request KYB verification for a provider



# Save KYB draft
Source: https://hevninc.mintlify.app/api-reference/b2b/save-kyb-draft

/openapi.json put /api/v1/kyb/b2b/kyb/draft
Save KYB draft data locally. Documents must be uploaded separately via POST /kyb/draft/documents.



# Get cross-chain payin quote
Source: https://hevninc.mintlify.app/api-reference/balance/get-cross-chain-payin-quote

/openapi.json post /api/v1/balance/payin/quote
Create a quote to deposit from any chain to Base USDC.



# Get payout quote
Source: https://hevninc.mintlify.app/api-reference/balance/get-payout-quote

/openapi.json post /api/v1/balance/payout/quote
Get quote for payout to contact. Auto-detects payment channel (IBAN/onchain/internal).



# Get wallet balances
Source: https://hevninc.mintlify.app/api-reference/balance/get-wallet-balances

/openapi.json get /api/v1/balance
Get OMNI, NEAR, EVM and Swipelux wallet balances for authenticated user.



# Activate multiple bank rails
Source: https://hevninc.mintlify.app/api-reference/banks/activate-multiple-bank-rails

/openapi.json post /api/v1/banks/activate
Create or upsert Bank rows for multiple rails in one request. Returns a per-rail result so one pending or failed rail does not abort the batch.



# Get a pooled bank payin quote
Source: https://hevninc.mintlify.app/api-reference/banks/get-a-pooled-bank-payin-quote

/openapi.json post /api/v1/banks/payin/quote
Create a Swipelux quote for paying into the user's custodial wallet via a pooled bank rail.



# List all bank rails
Source: https://hevninc.mintlify.app/api-reference/banks/list-all-bank-rails

/openapi.json get /api/v1/banks
Return every supported bank rail. Rails the user has activated come from the Bank table (with status / iban_data); rails the user has not activated are returned from the static BANK_INFO registry with status=not_started and iban_data=None. If a rail's provider KYC is APPROVED but no ACTIVE Bank row exists yet, syncs lazily from Swipelux / Align before returning.



# Submit a pooled bank payin quote
Source: https://hevninc.mintlify.app/api-reference/banks/submit-a-pooled-bank-payin-quote

/openapi.json post /api/v1/banks/payin/quote/submit
Execute a Swipelux payin quote and return payment instructions.



# Freeze card
Source: https://hevninc.mintlify.app/api-reference/cards/freeze-card

/openapi.json post /api/v1/cards/{card_id}/freeze
Temporarily freeze a card. Can be unfrozen later.



# Get card by ID
Source: https://hevninc.mintlify.app/api-reference/cards/get-card-by-id

/openapi.json get /api/v1/cards/{card_id}
Get single card details.



# Get KYC verification link
Source: https://hevninc.mintlify.app/api-reference/cards/get-kyc-verification-link

/openapi.json post /api/v1/cards/kyc/link
Get link for user to complete KYC verification in browser.



# Get user's cards
Source: https://hevninc.mintlify.app/api-reference/cards/get-users-cards

/openapi.json get /api/v1/cards
Sync cards from Wirex and return the list.



# Issue new card
Source: https://hevninc.mintlify.app/api-reference/cards/issue-new-card

/openapi.json post /api/v1/cards
Issue a new virtual or physical card. User must complete KYC first.



# Pre-approve card issuance
Source: https://hevninc.mintlify.app/api-reference/cards/pre-approve-card-issuance

/openapi.json post /api/v1/cards/pre-approve
Check Wirex KYC prerequisites and return a verification URL if all required user fields are present.



# Reveal full card details
Source: https://hevninc.mintlify.app/api-reference/cards/reveal-full-card-details

/openapi.json post /api/v1/cards/{card_id}/details
Get full card number (PAN), CVV and expiry. Requires wallet signature for confirmation.



# Set card label
Source: https://hevninc.mintlify.app/api-reference/cards/set-card-label

/openapi.json put /api/v1/cards/{card_id}/label
Set or clear a user-defined label (nickname) for a card. Local-only, not sent to provider.



# Set card limit
Source: https://hevninc.mintlify.app/api-reference/cards/set-card-limit

/openapi.json put /api/v1/cards/{card_id}/limit
Set daily spending limit for a card.



# Unfreeze card
Source: https://hevninc.mintlify.app/api-reference/cards/unfreeze-card

/openapi.json post /api/v1/cards/{card_id}/unfreeze
Unfreeze a previously frozen card.



# Approve contract by client or contractor
Source: https://hevninc.mintlify.app/api-reference/contracts/approve-contract-by-client-or-contractor

/openapi.json post /api/v1/documents/contracts/{contract_id}/approve



# Create a new contract
Source: https://hevninc.mintlify.app/api-reference/contracts/create-a-new-contract

/openapi.json post /api/v1/documents/contracts



# Delete contract
Source: https://hevninc.mintlify.app/api-reference/contracts/delete-contract

/openapi.json delete /api/v1/documents/contracts/{contract_id}



# Get contract by ID
Source: https://hevninc.mintlify.app/api-reference/contracts/get-contract-by-id

/openapi.json get /api/v1/documents/contracts/{contract_id}



# List contracts for current user
Source: https://hevninc.mintlify.app/api-reference/contracts/list-contracts-for-current-user

/openapi.json get /api/v1/documents/contracts



# List fillable document templates and their fields
Source: https://hevninc.mintlify.app/api-reference/contracts/list-fillable-document-templates-and-their-fields

/openapi.json get /api/v1/documents/contracts/templates



# Pause contract
Source: https://hevninc.mintlify.app/api-reference/contracts/pause-contract

/openapi.json post /api/v1/documents/contracts/{contract_id}/pause



# Preview contract document generated from a saved contract
Source: https://hevninc.mintlify.app/api-reference/contracts/preview-contract-document-generated-from-a-saved-contract

/openapi.json get /api/v1/documents/contracts/{contract_id}/preview



# Set contractor payment methods for contract
Source: https://hevninc.mintlify.app/api-reference/contracts/set-contractor-payment-methods-for-contract

/openapi.json put /api/v1/documents/contracts/{contract_id}/payment_methods



# Update contract terms and schedule
Source: https://hevninc.mintlify.app/api-reference/contracts/update-contract-terms-and-schedule

/openapi.json patch /api/v1/documents/contracts/{contract_id}



# Create a document for e-signing via Firma
Source: https://hevninc.mintlify.app/api-reference/documents/create-a-document-for-e-signing-via-firma

/openapi.json post /api/v1/documents/create



# List uploaded documents
Source: https://hevninc.mintlify.app/api-reference/documents/list-uploaded-documents

/openapi.json get /api/v1/documents
List user-uploaded documents by filter type.



# Upload a document
Source: https://hevninc.mintlify.app/api-reference/documents/upload-a-document

/openapi.json post /api/v1/documents/upload
Upload a document to storage. Returns document_id for referencing.



# Download account confirmation PDF
Source: https://hevninc.mintlify.app/api-reference/exports/download-account-confirmation-pdf

/openapi.json get /api/v1/transactions/export/account_confirmation/{bank_id}
Generate and return account confirmation PDF for a Bank row.



# Download account statement PDF
Source: https://hevninc.mintlify.app/api-reference/exports/download-account-statement-pdf

/openapi.json get /api/v1/transactions/export/account_statement/{bank_id}
Generate and return account statement PDF with transactions for the period.



# Create incoming invoice from uploaded document
Source: https://hevninc.mintlify.app/api-reference/invoices/create-incoming-invoice-from-uploaded-document

/openapi.json post /api/v1/documents/contracts/invoices/uploaded



# Create invoice
Source: https://hevninc.mintlify.app/api-reference/invoices/create-invoice

/openapi.json post /api/v1/documents/contracts/invoices



# Create invoice from contract
Source: https://hevninc.mintlify.app/api-reference/invoices/create-invoice-from-contract

/openapi.json post /api/v1/documents/contracts/{contract_id}/create-invoice



# Generate invoices for multiple contracts
Source: https://hevninc.mintlify.app/api-reference/invoices/generate-invoices-for-multiple-contracts

/openapi.json post /api/v1/documents/contracts/invoices/batch_invoicing



# Get invoice by ID
Source: https://hevninc.mintlify.app/api-reference/invoices/get-invoice-by-id

/openapi.json get /api/v1/documents/contracts/invoices/{invoice_id}



# List invoices for current user
Source: https://hevninc.mintlify.app/api-reference/invoices/list-invoices-for-current-user

/openapi.json get /api/v1/documents/contracts/invoices



# Update invoice (set transaction_hash)
Source: https://hevninc.mintlify.app/api-reference/invoices/update-invoice-set-transaction_hash

/openapi.json put /api/v1/documents/contracts/invoices/{invoice_id}



# MCP API
Source: https://hevninc.mintlify.app/api-reference/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`.


# Get USDC balance on Base
Source: https://hevninc.mintlify.app/api-reference/mcp/get-usdc-balance-on-base

/openapi.json get /api/v1/mcp/get_balance



# REST API overview
Source: https://hevninc.mintlify.app/api-reference/overview

REST endpoints used internally by HEVN CLI.

This section has two API reference layers:

* **Generated API Reference** is powered by the live HEVN OpenAPI schema from `https://api.hevn.finance/openapi.json` and enables Mintlify's endpoint pages, request examples, and interactive API Playground.
* **CLI wrapper notes** live in the CLI tab and document the REST endpoints that the current CLI calls through `src/hevn_cli/api/*`.

## Base URL

The generated OpenAPI reference uses:

```bash theme={null}
https://api.hevn.finance
```

The CLI builds requests from the configured API base URL:

```bash theme={null}
https://api.hevn.finance/api/v1
```

The base URL can be selected through `HEVN_ENV`, saved login config, or `HEVN_BASE_URL`.

```bash theme={null}
export HEVN_ENV=prod
export HEVN_BASE_URL=https://api.hevn.finance/api/v1
```

## API clients

| Client      | Source                       | Auth mode         | Used for                                                                            |
| ----------- | ---------------------------- | ----------------- | ----------------------------------------------------------------------------------- |
| `AppApi`    | `src/hevn_cli/api/app.py`    | HEVN API key      | Account, profile, contacts, invoices, contracts, banks, cards, quotes, transactions |
| `McpApi`    | `src/hevn_cli/api/mcp.py`    | Same HEVN API key | Balance, API-key introspection, and app-scoped transfers                            |
| `PublicApi` | `src/hevn_cli/api/public.py` | Public            | FX rates and public invoices                                                        |

## Request behavior

All requests:

* send `Accept: application/json`,
* send the configured API key for authenticated clients,
* use a 60 second HTTP timeout,
* send query parameters only when their values are not `None`,
* parse non-empty responses as JSON,
* raise a CLI `HevnError` for HTTP status codes `>= 400`.

When `--debug` or `HEVN_DEBUG=1` is enabled, error output can include the generated curl command.

Mutating HTTP methods (`POST`, `PUT`, `PATCH`, `DELETE`) are intercepted by `--dry-run` / `HEVN_DRY_RUN=1` before the network call is made.

## Common response handling

The CLI does not enforce a shared backend response schema across endpoints. It passes backend JSON through to command formatters and wraps `--json` / `--yaml` command output in a CLI envelope.

For integration code, use the endpoint-specific objects returned by the backend and treat fields shown in command output as convenience projections rather than exhaustive schemas.

## Endpoint index

<CardGroup>
  <Card title="Authentication" icon="key-round" href="/api-reference/authentication">
    Header modes, login config, and idempotency headers.
  </Card>
</CardGroup>


# Public API
Source: https://hevninc.mintlify.app/api-reference/public-api

Unauthenticated REST endpoints used by HEVN CLI PublicApi.

`PublicApi` sends only `Accept: application/json`.

## FX rate

```http theme={null}
GET /utils/rates/{currency}
```

CLI surface:

```bash theme={null}
hevn rate EUR
hevn rate --currency AED --yaml
```

Path parameters:

| Parameter  | Type   | Purpose                             |
| ---------- | ------ | ----------------------------------- |
| `currency` | string | Currency code to price against USD. |

Example response fields consumed by the CLI:

```json theme={null}
{
  "usdRate": "1.08",
  "bankTransfer": "1.08",
  "card": "1.10"
}
```

## Public invoice

```http theme={null}
GET /public/invoices/{invoice_id}
```

CLI surface:

```bash theme={null}
hevn invoice get <invoice-id> --public
```

Path parameters:

| Parameter    | Type   | Purpose            |
| ------------ | ------ | ------------------ |
| `invoice_id` | string | Public invoice id. |

The CLI renders the returned invoice with the same invoice formatter used for authenticated invoice reads.


# Get Public Invoice
Source: https://hevninc.mintlify.app/api-reference/public/get-public-invoice

/openapi.json get /api/v1/public/invoices/{invoice_id}
Public invoice details — no auth required.



# Export transactions
Source: https://hevninc.mintlify.app/api-reference/transactions/export-transactions

/openapi.json get /api/v1/transactions/export
Export transactions as CSV or XLSX file.



# Get user transactions
Source: https://hevninc.mintlify.app/api-reference/transactions/get-user-transactions

/openapi.json get /api/v1/transactions
Get latest user transactions sorted by time.



# Transaction volume breakdown
Source: https://hevninc.mintlify.app/api-reference/transactions/transaction-volume-breakdown

/openapi.json get /api/v1/transactions/breakdown
Volume + count grouped by tag or type, with the same filters as the list.



# Transaction volume breakdown over time
Source: https://hevninc.mintlify.app/api-reference/transactions/transaction-volume-breakdown-over-time

/openapi.json get /api/v1/transactions/breakdown/series
Volume + count grouped by tag or type, split into time buckets across the fromDate..toDate range. Granularity is auto-picked: >6 months → month, >30 days → week, otherwise day. Empty periods are returned as zero-filled buckets so the frontend gets a complete x-axis. Same filter set as /transactions and /transactions/breakdown. `fromDate` and `toDate` are required.



# Create contact
Source: https://hevninc.mintlify.app/api-reference/user/create-contact

/openapi.json post /api/v1/user/contact
Create a new contact for the current user.



# Create or get current user
Source: https://hevninc.mintlify.app/api-reference/user/create-or-get-current-user

/openapi.json put /api/v1/user/kyc
Create or update user profile data for KYC.



# Delete contact
Source: https://hevninc.mintlify.app/api-reference/user/delete-contact

/openapi.json delete /api/v1/user/contacts/{contact_id}
Delete a contact.



# Get current user
Source: https://hevninc.mintlify.app/api-reference/user/get-current-user

/openapi.json get /api/v1/user
Get the profile of the currently authenticated user.



# Get KYC status
Source: https://hevninc.mintlify.app/api-reference/user/get-kyc-status

/openapi.json get /api/v1/user/kyc/status
Check the current KYC verification status. Use provider=align for Align.



# Get user contacts
Source: https://hevninc.mintlify.app/api-reference/user/get-user-contacts

/openapi.json get /api/v1/user/contacts
Get all contacts for the current user.



# Prevalidate bank contact details
Source: https://hevninc.mintlify.app/api-reference/user/prevalidate-bank-contact-details

/openapi.json post /api/v1/user/contact/bank/validate
Validate bank identifiers before creating a contact.



# Share KYB link
Source: https://hevninc.mintlify.app/api-reference/user/share-kyb-link

/openapi.json post /api/v1/kyb/user/share_kyb_link
Send a KYB verification link to the specified email.



# Submit KYC data
Source: https://hevninc.mintlify.app/api-reference/user/submit-kyc-data

/openapi.json post /api/v1/user/kyc_link
Get Swipelux KYC verification link.



# Update contact name
Source: https://hevninc.mintlify.app/api-reference/user/update-contact-name

/openapi.json patch /api/v1/user/contacts/{contact_id}
Update safe contact metadata.



# Get FX rates
Source: https://hevninc.mintlify.app/api-reference/utils/get-fx-rates

/openapi.json get /api/v1/utils/rates/{currency}
Public endpoint. Returns FX rates from the given currency to USD: `bankTransfer` (Swipelux), `card` (Wirex), and `usdRate` (exchangerate-api.com). `usdRate` is populated for every currency in the invoice Currency enum (G10 + AED/HKD).



# Account and profile
Source: https://hevninc.mintlify.app/commands/account

Inspect the active HEVN account, update profile fields, and manage KYC status.

## Account summary

Show the active account:

```bash theme={null}
hevn account get
```

Introspect the active API key, owning app, scopes, balance, and spend limit:

```bash theme={null}
hevn whoami
hevn whoami --yaml
```

List account state, auth state, balances, and MCP allowance:

```bash theme={null}
hevn account list --yaml
```

`profile` is an alias for `account`, so these commands are equivalent:

```bash theme={null}
hevn account get
hevn profile get
```

## Update profile

Update identity or address fields:

```bash theme={null}
hevn profile set \
  --first-name Ada \
  --last-name Lovelace \
  --street-address "1 Example Street" \
  --city London \
  --country GB \
  --zip SW1A1AA
```

Business accounts can set an entity name:

```bash theme={null}
hevn profile set --entity-name "Example Ltd"
```

At least one profile field is required.

## KYC

Get a KYC link or status:

```bash theme={null}
hevn account kyc
hevn account kyc --status
hevn account kyc --provider align --status
```

The default provider is `swipelux`. Supported provider values are passed through to the HEVN backend.

## KYB

There is no dedicated KYB flow in the CLI today. KYB endpoints are present in the REST OpenAPI schema for direct API integrations, but `hevn` currently exposes profile/KYC commands only.

## Status

Use the top-level status command for a compact health check:

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

Use `--json` or `--yaml` when integrating account status into automation.


# Cards and banks
Source: https://hevninc.mintlify.app/commands/cards-banks

Inspect card status, card KYC links, available bank rails, and bank detail validation.

## Cards

List cards:

```bash theme={null}
hevn cards list
hevn cards list --yaml
```

Get card availability and KYC status:

```bash theme={null}
hevn cards status
```

Get a card KYC link:

```bash theme={null}
hevn cards kyc-link
hevn cards kyc-link --no-qr
```

The CLI can print a terminal QR code for KYC links unless `--no-qr` is provided.

## Banks

List active or requested banks:

```bash theme={null}
hevn banks list
```

Show all available rails:

```bash theme={null}
hevn banks list --all
```

Get details for a rail:

```bash theme={null}
hevn banks details --rail uaefts_named_zand
```

## Validate bank details

Validate ACH routing details:

```bash theme={null}
hevn banks validate \
  --bank-type ach \
  --routing-number 021000021 \
  --country US
```

Validate SWIFT details:

```bash theme={null}
hevn banks validate \
  --bank-type swift \
  --bic DEUTDEFF \
  --country DE
```

Validate SEPA or UAEFTS details:

```bash theme={null}
hevn banks validate \
  --bank-type sepa \
  --iban DE89370400440532013000 \
  --country DE
```

Validation output includes errors, warnings, and lookup data when the backend returns them.


# Contacts
Source: https://hevninc.mintlify.app/commands/contacts

Create, list, update, and delete email, crypto, and bank contacts.

Contacts are reusable payout destinations. The CLI supports three contact types:

* `email`
* `crypto`
* `bank`

## List contacts

```bash theme={null}
hevn contacts list
hevn contacts list --yaml
hevn contacts list --limit 500 --offset 0 --json
```

YAML output normalizes contact records for agents and scripts.

## Email contacts

Create an email contact:

```bash theme={null}
hevn contacts new \
  --type email \
  --name "Vendor" \
  --email vendor@example.com
```

## Crypto contacts

Create an on-chain contact:

```bash theme={null}
hevn contacts new \
  --type crypto \
  --name "Treasury wallet" \
  --wallet-address 0x0000000000000000000000000000000000000000 \
  --chain base \
  --currency USDC
```

Optionally attach a linked email:

```bash theme={null}
hevn contacts new \
  --type crypto \
  --wallet-address 0x0000000000000000000000000000000000000000 \
  --chain base \
  --currency USDC \
  --email wallet-owner@example.com
```

## Bank contacts

Bank contacts require an account holder type:

```bash theme={null}
hevn contacts new \
  --type bank \
  --bank-type sepa \
  --account-holder-type business \
  --account-holder-business-name "Vendor GmbH" \
  --bank-name "Example Bank" \
  --iban DE89370400440532013000 \
  --country DE \
  --currency EUR
```

Supported bank account types:

| Type     | Typical fields                                                    |
| -------- | ----------------------------------------------------------------- |
| `sepa`   | `--iban`, `--country`, `--currency`, optional `--bic`             |
| `ach`    | `--account-number`, `--routing-number`, `--country`, `--currency` |
| `swift`  | `--account-number`, `--bic`, `--country`, `--currency`            |
| `uaefts` | `--iban`, optional `--bic`                                        |

## Update metadata

Existing contact payment details cannot be replaced. You can update contact metadata such as name and relationship:

```bash theme={null}
hevn contacts new \
  --contact-id <contact-id> \
  --name "Updated name" \
  --relationship external
```

## Delete a contact

```bash theme={null}
hevn contacts delete <contact-id>
hevn contacts delete --contact-id <contact-id> --yes
```

<Warning>
  Delete operations prompt for confirmation unless `--yes` is provided.
</Warning>


# Contracts
Source: https://hevninc.mintlify.app/commands/contracts

Upload existing contracts, generate HEVN templates, preview, approve, update, pause, and manage payment methods.

## List and inspect contracts

```bash theme={null}
hevn contracts list
hevn contracts list --yaml
hevn contracts get <contract-id>
hevn contracts preview --id <contract-id> --yaml
```

Print rendered contract body when previewing:

```bash theme={null}
hevn contracts preview --id <contract-id> --document
```

## Contract statuses

Common statuses:

```text theme={null}
pending_approval_by_contractor
pending_approval_by_client
active
completed
cancelled
paused
```

## Upload an existing contract

Use `contracts new` when you already have a contract file and want to attach it as an active contract:

```bash theme={null}
hevn contracts new \
  --contractor-email contractor@example.com \
  --document-path ./contract.pdf \
  --amount 1000 \
  --currency USD \
  --period monthly \
  --activation-at 2026-07-10 \
  --yaml
```

You can attach a previously uploaded document id:

```bash theme={null}
hevn contracts new \
  --client-email client@example.com \
  --document-id <document-id> \
  --type custom \
  --field contractorName="Your Company" \
  --field clientName="Counterparty"
```

`contracts new` creates the contract with `status=active` and does not start the signing flow.

## Generate a HEVN contract

Use `contracts generate` when HEVN should generate the contract from a backend template:

```bash theme={null}
hevn contracts generate \
  --contractor-email contractor@example.com \
  --type default_contractor \
  --amount 1000 \
  --currency USD \
  --period monthly \
  --activation-at 2026-05-01 \
  --yaml
```

Generated contract types must start with `default_`. Use `contracts new` for uploaded existing contracts.

## Hire shortcut

`hevn hire` is a shortcut for generating a `default_contractor` contract:

```bash theme={null}
hevn hire \
  --contractor-email contractor@example.com \
  --job-title "Engineer" \
  --scope-description "Full-time engineering work" \
  --amount 5000 \
  --currency USD \
  --period monthly \
  --start-date 2026-05-01 \
  --yaml
```

Preview and approve:

```bash theme={null}
hevn contracts preview --id <contract-id> --yaml
hevn contracts --id <contract-id> approve --yaml
```

## Update terms and schedule

Contract creators can edit terms and invoice schedule:

```bash theme={null}
hevn contracts update \
  --id <contract-id> \
  --period monthly \
  --activation-at 2026-07-10 \
  --field 'paymentTerms=Payment on the 10th for the previous month' \
  --yaml
```

Use `--activation-at` as the recurring invoice anchor date.

## Payment methods

Set contract payment methods with repeatable JSON objects:

```bash theme={null}
hevn contracts payment-methods \
  --id <contract-id> \
  --payment-method '{"accountType":"email","email":"contractor@example.com"}' \
  --yaml
```

Or pass a JSON array:

```bash theme={null}
hevn contracts payment-methods \
  --id <contract-id> \
  --payment-methods-json '[{"accountType":"email","email":"contractor@example.com"}]'
```

## Pause and delete

```bash theme={null}
hevn contracts pause --id <contract-id>
hevn contracts delete --id <contract-id> --yes
```

<Warning>
  Before creating a contract from a file, determine which party is the current HEVN user. Use `--contractor-email` when the current user is the client, and `--client-email` when the current user is the contractor.
</Warning>


# Invoices
Source: https://hevninc.mintlify.app/commands/invoices

List, create, upload, decline, batch, and pay HEVN invoices.

## List invoices and bills

List all invoices:

```bash theme={null}
hevn invoice list
hevn invoice list --yaml
```

List incoming bills for the current account:

```bash theme={null}
hevn bills
hevn bills --yaml
```

## Get an invoice

```bash theme={null}
hevn invoice get <invoice-id>
hevn invoice get --invoice-id <invoice-id> --yaml
```

Use the public invoice endpoint:

```bash theme={null}
hevn invoice get <invoice-id> --public
```

## Create an invoice

Interactive flow:

```bash theme={null}
hevn invoice new
```

Non-interactive flow:

```bash theme={null}
hevn invoice new \
  --contractor-email vendor@example.com \
  --contractor-name Vendor \
  --client-email you@example.com \
  --client-name "Your Company" \
  --item "Consulting:1:100" \
  --due-date 2026-06-01
```

Items can be provided as repeatable `--item` flags:

```bash theme={null}
hevn invoice new \
  --contractor-email vendor@example.com \
  --item "Design:2:150" \
  --item '{"name":"Review","quantity":1,"price":75}'
```

Or as a JSON array:

```bash theme={null}
hevn invoice new \
  --contractor-email vendor@example.com \
  --items '[{"name":"Consulting","quantity":1,"price":"100"}]'
```

## Upload an incoming invoice

Upload an invoice PDF or document and create an incoming invoice record:

```bash theme={null}
hevn invoice upload-incoming \
  --path ./invoice.pdf \
  --contractor-email vendor@example.com \
  --items '[{"name":"Consulting","quantity":1,"price":"100"}]'
```

Uploaded documents are cached in the local config so a path can later resolve to its document id.

## Create from contract

```bash theme={null}
hevn invoice new \
  --contract-id <contract-id> \
  --period-start 2026-06-01 \
  --add-item "Extra support:1:250"
```

The current user's address is required for contract invoice creation.

## Batch invoicing

```bash theme={null}
hevn invoice batch \
  --contract '{"contractId":"<contract-id>","period":0,"memo":"May payroll","items":[{"name":"Monthly services","quantity":1,"price":"5000"}]}' \
  --yaml
```

Or pass an array:

```bash theme={null}
hevn invoice batch \
  --contracts-json '[{"contractId":"<contract-id>","period":0,"items":[{"name":"Services","quantity":1,"price":"5000"}]}]'
```

## Decline an invoice

```bash theme={null}
hevn invoice decline --invoice-id <invoice-id> --yes --yaml
```

## Pay an invoice

Invoice payment is handled by the transfer command:

```bash theme={null}
hevn transfer --invoice-id <invoice-id> --memo "Invoice payment"
```


# Money movement
Source: https://hevninc.mintlify.app/commands/money-movement

Check balances, create deposit quotes, inspect transactions, and send app-scoped transfers.

## Balance

Show transfer wallet balance and remaining allowance:

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

Show the broader app account balance through account commands:

```bash theme={null}
hevn account list --yaml
```

## FX rates

Fetch a public FX rate to USD:

```bash theme={null}
hevn rate EUR
hevn rate --currency AED --yaml
```

## Crypto deposits

Create a deposit quote:

```bash theme={null}
hevn deposit 100 usdc base
```

Equivalent option form:

```bash theme={null}
hevn deposit --amount 100 --currency usdc --chain base
```

The result may include a deposit address and memo. Send funds only to the returned deposit details.

## Bank deposits

For pooled ACH or wire bank accounts:

```bash theme={null}
hevn deposit \
  --from bank \
  --bank-id <bank-account-id> \
  --amount 100 \
  --memo "Funding treasury"
```

Check pending bank deposits:

```bash theme={null}
hevn pending-deposits
hevn pending-deposits --bank-id <bank-account-id> --yaml
```

## Pay an invoice

```bash theme={null}
hevn transfer --invoice-id <invoice-id> --memo "Invoice payment"
```

The command loads invoice details and submits an app-scoped transfer. The backend resolves the owning app from the configured API key; no app id is required.

## Transfer by email

```bash theme={null}
hevn transfer email vendor@example.com 25 --memo "Thanks"
```

If an email contact does not exist, the CLI creates one before submitting the transfer.

## Transfer to a contact

Send to an email or internal contact:

```bash theme={null}
hevn transfer contact <contact-id> 25 --memo "Thanks"
```

Send to a bank contact through a payout quote:

```bash theme={null}
hevn transfer contact \
  --contact-id <contact-id> \
  --amount 25 \
  --bank-account-id <bank-account-id> \
  --yes \
  --memo "Bank payout"
```

Use an existing quote:

```bash theme={null}
hevn transfer contact \
  --contact-id <contact-id> \
  --quote-id <quote-id> \
  --memo "Bank payout"
```

## Transactions

List recent transactions:

```bash theme={null}
hevn transfer list
hevn transfer list --limit 100 --offset 0 --yaml
```

<Note>
  Write commands generate an idempotency key automatically when one is not supplied. Pass `--idempotency-key` when replay protection must be controlled by your own system.
</Note>


# Configuration
Source: https://hevninc.mintlify.app/configuration

Configure HEVN environments, API credentials, output formats, and debug behavior.

## Config file

By default, HEVN CLI stores local configuration at:

```text theme={null}
~/.config/hevn-cli/config.json
```

Override the config path with:

```bash theme={null}
export HEVN_CLI_CONFIG="/path/to/config.json"
```

The config file is written with restrictive file permissions when possible.

## Environments

Select an environment globally:

```bash theme={null}
export HEVN_ENV="prod"
```

Or per command:

```bash theme={null}
hevn --env dev account get
hevn --env local login
```

Built-in environments:

| Environment | Site URL                        | API URL                               |
| ----------- | ------------------------------- | ------------------------------------- |
| `prod`      | `https://app.gethevn.com`       | `https://api.hevn.finance/api/v1`     |
| `dev`       | `https://app-beta.hevn.finance` | `https://dev-api.hevn.finance/api/v1` |
| `local`     | `http://localhost:8081`         | Local or configured development API   |

You can also override URLs directly:

```bash theme={null}
export HEVN_BASE_URL="https://api.hevn.finance/api/v1"
export HEVN_SITE_URL="https://app.gethevn.com"
```

## API keys

The preferred interactive auth path is:

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

This saves:

* `api_key`
* `api_key_header`
* `base_url`, when returned by the login callback

For automation, either save a key directly:

```bash theme={null}
hevn login --api-key hvn_...
hevn login --api-key hvn_... --api-key-header X-Api-Key
hevn login --api-key hvn_... --api-base-url https://api.example.com/api/v1
```

or set credentials through environment variables:

```bash theme={null}
export HEVN_API_KEY="hvn_..."
# Optional. Defaults to Authorization.
export HEVN_API_KEY_HEADER="Authorization"
```

`Authorization` mode adds a `Bearer` prefix automatically when the key does not already start with one. Use `X-Api-Key` only when your backend deployment requires that header:

```bash theme={null}
export HEVN_API_KEY_HEADER="X-Api-Key"
```

The CLI no longer uses `HEVN_APP_ID`; transfer endpoints derive the owning app from the API key.

## Output formats

Human output is optimized for terminal use with Rich tables and panels. For scripts and agents, prefer JSON or YAML. You can set output globally:

```bash theme={null}
hevn --json contacts list
hevn --yaml invoice list
export HEVN_OUTPUT_FORMAT=yaml
```

or per command:

```bash theme={null}
hevn contacts list --json
hevn invoice list --yaml
hevn contracts preview --id <contract-id> --yaml
```

Structured success output is wrapped as `ok`, `data`, `meta`, and `warnings`. Structured error output is wrapped as `ok`, `errorCode`, `errorType`, `error`, and `exitCode`.

## Automation controls

Use non-interactive mode to refuse prompts and return structured `INTERACTIVE_REQUIRED` errors when a required flag is missing:

```bash theme={null}
hevn --non-interactive --yaml contacts new --type email
```

Use dry-run mode to preflight mutating HTTP calls without sending the request:

```bash theme={null}
hevn --dry-run transfer --invoice-id <invoice-id> --memo "Invoice payment"
```

Inspect the full CLI contract for agents and scripts:

```bash theme={null}
hevn --schema
hevn --schema --yaml
hevn agent-skill
```

## Debugging

Use `--debug` to include invocation and curl details in error output:

```bash theme={null}
hevn --debug invoice get <invoice-id>
```

Or set:

```bash theme={null}
export HEVN_DEBUG=1
```

<Warning>
  Debug output can include sensitive headers and request payloads. Avoid sharing raw debug logs without redaction.
</Warning>


# Connect AI coding agents
Source: https://hevninc.mintlify.app/connect-agents

Expose the HEVN CLI to Claude Code, Codex, Cursor, and other MCP agents with a single install command.

HEVN CLI ships a built-in [Model Context Protocol](https://modelcontextprotocol.io)
server. It exposes every CLI command as an MCP tool, so any MCP-speaking coding
agent can act on your HEVN account directly — checking balances, creating
invoices, sending transfers — without bespoke per-agent integrations or pasted
instructions.

`hevn mcp install` registers that server in every agent it detects on your
machine, in one command.

## Supported agents

| Agent          | Config file                                         |
| -------------- | --------------------------------------------------- |
| Claude Code    | `~/.claude.json`                                    |
| Claude Desktop | `claude_desktop_config.json` (OS-specific location) |
| Cursor         | `~/.cursor/mcp.json`                                |
| Windsurf       | `~/.codeium/windsurf/mcp_config.json`               |
| Codex CLI      | `~/.codex/config.toml`                              |

## Install

Authenticate once, then install:

```bash theme={null}
hevn login        # the MCP server reuses this credential
hevn mcp install  # register hevn in every detected agent
```

Restart the agent and ask it something like "what's my HEVN balance?". A read
runs immediately; a transfer or delete is flagged so the agent asks you to
confirm first.

Check what was detected and installed:

```bash theme={null}
hevn mcp list
```

## How it works

* **One adapter, many agents.** Every supported agent speaks MCP, so a single
  server reaches all of them. The installer knows where each agent stores its
  config (`mcpServers` JSON for most, a `[mcp_servers.hevn]` table for Codex)
  and writes the entry in place, preserving everything else.
* **The agent learns hevn automatically.** The packaged agent guide
  (`hevn agent-skill`) is served as the MCP server's instructions, and each
  tool carries the command's schema and help. You don't configure prompts per
  agent.
* **Reuses the CLI verbatim.** A tool call shells out to `hevn` with
  `--json --non-interactive`, so authentication, dry-run previews, idempotency,
  and the structured `{ok, …}` envelope behave exactly as they do on the
  command line.
* **Danger levels drive confirmation.** Each command's danger level becomes an
  MCP annotation: reads are marked read-only, while `mutate`, `destructive`, and
  `money` commands are flagged so the host prompts for approval. Transfers
  remain bounded by your on-chain spend permission regardless of the agent.

## Authentication

By default no API key is written into agent configs. `hevn mcp serve` reads the
credential saved by `hevn login`, just like every other CLI command, so your key
stays in one place.

If a tool call comes back with `AUTH_REQUIRED` or `AUTH_INVALID` (no key yet, or
an expired one), the agent can sign you in itself: it calls the **`login`** tool,
which opens your browser to HEVN and saves the new credential locally — the
server runs on your machine, so the browser flow works just like `hevn login`.
Pass `api_key` to that tool to save an existing `hvn_` key instead of opening a
browser. There is also a **`logout`** tool to clear the saved credential.

Use `--with-key` to embed the current `HEVN_API_KEY` in each config when you
need a self-contained setup (for example, a different machine or user):

```bash theme={null}
hevn mcp install --with-key
```

<Warning>
  `--with-key` writes your API key into each agent's config file in plaintext.
  Prefer the default (`hevn login`) on shared machines.
</Warning>

## Targeting and removal

```bash theme={null}
hevn mcp install --client cursor          # target one agent (repeatable)
hevn mcp install --client cursor --client codex
hevn mcp install --all                    # also write configs for agents not detected
hevn mcp uninstall                        # remove the hevn server from detected agents
hevn mcp uninstall --client cursor        # remove from a specific agent
```

## Manual configuration

`hevn mcp install` is just a convenience over the standard MCP server config. To
wire an agent up by hand, add an `stdio` server that runs `hevn mcp serve`:

```json theme={null}
{
  "mcpServers": {
    "hevn": {
      "command": "hevn",
      "args": ["mcp", "serve"]
    }
  }
}
```

For Codex (TOML):

```toml theme={null}
[mcp_servers.hevn]
command = "hevn"
args = ["mcp", "serve"]
```

<Note>
  Use an absolute path to `hevn` (for example `/opt/homebrew/bin/hevn`) if your
  agent launches with a minimal `PATH`. `hevn mcp install` resolves this for you.
</Note>


# Development
Source: https://hevninc.mintlify.app/development

Install dependencies, run tests, build distributions, and publish HEVN CLI.

## Local setup

Install dependencies with Poetry:

```bash theme={null}
poetry install
poetry run hevn --help
```

Run commands against a selected environment:

```bash theme={null}
poetry run hevn --env dev account get
poetry run hevn --env local login
```

## Tests and lint

Run tests:

```bash theme={null}
poetry run pytest
```

Run lint:

```bash theme={null}
poetry run ruff check .
```

## Build

Build source and wheel distributions:

```bash theme={null}
poetry build
```

Smoke test a local wheel:

```bash theme={null}
pipx install dist/hevn_cli-0.1.0-py3-none-any.whl
hevn --help
```

Local wheel installs are useful for smoke testing, but they are not a good long-term `pipx` source because `pipx upgrade hevn-cli` reinstalls from the same local artifact.

## Publishing

PyPI publishing is handled by the `Publish to PyPI` GitHub Actions workflow. Run it manually from `main`.

The workflow:

* runs lint and tests,
* checks `hevn --help` on Ubuntu, macOS, and Windows,
* builds the package once from Ubuntu,
* publishes to PyPI with trusted publishing.

Configure the PyPI trusted publisher for:

| Field       | Value                                |
| ----------- | ------------------------------------ |
| Owner       | `hevn`                               |
| Repository  | `hevn-cli`                           |
| Workflow    | `.github/workflows/publish-pypi.yml` |
| Environment | `pypi`                               |

## Homebrew formula guidance

The Homebrew formula should install the PyPI package inside Homebrew's isolated Python virtualenv. Do not shell out to system `pip install hevn-cli` from the formula.

```ruby theme={null}
class HevnCli < Formula
  include Language::Python::Virtualenv

  desc "Command-line client for the HEVN backend API and MCP transfers"
  homepage "https://gethevn.com"
  url "https://files.pythonhosted.org/packages/source/h/hevn-cli/hevn_cli-0.1.0.tar.gz"
  sha256 "<sha256>"
  license "MIT"

  depends_on "python@3.12"

  def install
    virtualenv_install_with_resources
  end

  test do
    assert_match "HEVN backend CLI", shell_output("#{bin}/hevn --help")
  end
end
```


# HEVN CLI
Source: https://hevninc.mintlify.app/index

Install, authenticate, and operate HEVN payments, invoices, contracts, cards, and app-scoped transfers from the command line.

HEVN CLI is a standalone command-line wrapper for the HEVN backend API and app-scoped transfer endpoints. It is built primarily for AI agents and automation that need scriptable access to HEVN account data and payment workflows, while still providing human-readable terminal output for operators, finance teams, and developers.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install the CLI, sign in, and confirm your account in a few commands.
  </Card>

  <Card title="Configuration" icon="settings-2" href="/configuration">
    Configure environments, API keys, output formats, and debugging.
  </Card>

  <Card title="Agent workflows" icon="bot" href="/agent-workflows">
    Load the agent skill, inspect the CLI manifest, and run workflows safely.
  </Card>

  <Card title="Connect AI agents" icon="plug" href="/connect-agents">
    Expose the CLI to Claude Code, Codex, and Cursor over MCP with one command.
  </Card>

  <Card title="Money movement" icon="arrow-right-left" href="/commands/money-movement">
    Check balances, create deposit quotes, pay invoices, and transfer to contacts.
  </Card>

  <Card title="Contracts" icon="file-pen-line" href="/commands/contracts">
    Upload existing contracts, generate HEVN templates, approve contracts, and manage payment methods.
  </Card>
</CardGroup>

## What you can do

* Authenticate with `hevn login` and store a local app API key.
* Inspect account, KYC, balance, card, bank, contact, invoice, and contract state.
* Create contacts for email, crypto, and fiat payout destinations.
* Create invoices manually, from uploaded invoice documents, or from contracts.
* Generate HEVN contracts from templates or upload existing signed contracts.
* Move USDC by invoice, email recipient, contact, or payout quote.
* Emit human-readable tables or machine-readable JSON/YAML envelopes for automation.
* Print an agent-readable command manifest with `hevn --schema`.
* Connect MCP coding agents (Claude Code, Codex, Cursor) with `hevn mcp install`.

## Command shape

Most commands follow this pattern:

```bash theme={null}
hevn [global-options] <resource> <action> [options]
```

Common global options:

```bash theme={null}
hevn --env dev account get
hevn --base-url https://api.example.com/api/v1 account get
hevn --debug transfer --invoice-id <invoice-id>
hevn --dry-run transfer --invoice-id <invoice-id>
hevn --non-interactive --yaml contacts list
```

Most read and write commands also support command-local output flags:

```bash theme={null}
--json
--yaml
```

Use these flags for scripts, agent tools, CI jobs, and data extraction. In JSON/YAML mode, successful command output is wrapped as `ok`, `data`, `meta`, and `warnings`; error output is wrapped as `ok`, `errorCode`, `errorType`, `error`, and `exitCode`.

## Authentication model

`hevn login` opens the HEVN app in a browser, creates or selects an app, issues an app API key, and saves it in your local HEVN CLI config. Automation can save a key directly:

```bash theme={null}
hevn login --api-key hvn_...
```

One `hvn_...` API key is used for every authenticated endpoint, including transfers. The default header is `Authorization: Bearer hvn_...`; set `HEVN_API_KEY_HEADER=X-Api-Key` only when your backend deployment requires that header.

<Note>
  Transfer commands no longer require an app id. The backend resolves the owning app from the API key.
</Note>


# Quickstart
Source: https://hevninc.mintlify.app/quickstart

Install HEVN CLI, authenticate, and run your first account and balance commands.

## Prerequisites

Before you begin, you need:

* An active HEVN account.
* `pipx` (Python 3.11+) or Homebrew for an isolated end-user install.

## Install

### pipx (recommended)

`pipx` installs the CLI from PyPI into its own isolated environment:

```bash theme={null}
pipx install hevn-cli
hevn --help
```

Upgrade to the latest published release:

```bash theme={null}
pipx upgrade hevn-cli
```

### Homebrew

On macOS and Linux you can install from the HEVN tap:

```bash theme={null}
brew install hevn-inc/tap/hevn-cli
hevn --help
```

The tap is the formula source, so the first command both taps and installs. Upgrade with:

```bash theme={null}
brew upgrade hevn-cli
```

## Authenticate

Run the browser login flow:

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

The CLI opens HEVN, waits for a local callback, saves your app API key, and prints the config path. If you are on a remote machine or do not want the browser to open automatically, use:

```bash theme={null}
hevn login --no-open
```

For automation or remote environments, save an API key directly without opening a browser:

```bash theme={null}
hevn login --api-key hvn_...
```

The same `hvn_...` key is used for all authenticated CLI calls, including transfers.

## Confirm your account

Check the active account:

```bash theme={null}
hevn account get
```

Introspect the active API key, owning app, scopes, balance, and spend limit:

```bash theme={null}
hevn whoami
hevn whoami --yaml
```

List accounts in machine-readable form:

```bash theme={null}
hevn account list --yaml
```

Check transfer balance and allowance:

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

## First useful workflow

Create an email contact and transfer USDC:

```bash theme={null}
hevn contacts new --type email --name "Vendor" --email vendor@example.com
hevn contacts list --yaml
hevn transfer contact --contact-id <contact-id> --amount 25 --memo "Thanks"
```

Pay an invoice by id:

```bash theme={null}
hevn transfer --invoice-id <invoice-id> --memo "Invoice payment"
```

## Log out

Clear saved local credentials:

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

<Warning>
  `hevn logout` removes saved HEVN CLI credential fields from the local config file. It does not delete your HEVN account or revoke unrelated credentials.
</Warning>