Keys and permissions

Create a remote transfer key, grant its spender wallet a spend permission, restrict it by IP and lifetime spend, and revoke it.

A remote transfer key is useless until two things exist: the key, and a spend permission from your smart wallet to the key’s spender wallet. The app does both in one step. The API creates only the key, so the permission is always granted in the app.

Create a key in the app

Open Settings → Remote Transfers in the app and click Create remote transfer key. Give the key a name and set its spending limit — an amount and a period. Confirming does two things:

1. HEVN issues the key and predicts its spender wallet.
2. Your wallet signs a spend permission naming that spender wallet, with the limit you set.

The key is shown once. Copy it then: HEVN stores only its hash and cannot show it again. Keep it in a secret store on the machine that uses it, out of repositories, images and logs.

To change the limit later, open the key and update its spend permission. Your wallet signs a new permission that replaces the old one.

Create a key with the API

The key-management routes take your app session, not a remote transfer key:

Authorization: Bearer <session token>

Use this when you need an option the app does not expose — an IP allowlist or a lifetime maxSpend.

curl -X POST "https://api.hevn.finance/api/v1/remote_spend_limit/api_key" \
  -H "Authorization: Bearer $HEVN_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payroll bot",
    "ipRestriction": "203.0.113.10,203.0.113.11",
    "maxSpend": 5000
  }'

Field	Type	Required	Meaning
name	string	yes	A label for the key, shown in the app
ipRestriction	string	no	Comma-separated list of exact IP addresses the key may be used from. No CIDR ranges. Omit to allow any address
maxSpend	number	no	Lifetime USDC cap for this key, checked by HEVN on top of the onchain allowance. Omit for no cap

200 OK:

{
  "id": "6f1c2a7e-5b0d-4e8a-9a51-2f7d0c3b9e14",
  "name": "Payroll bot",
  "key": "rsl_Xk2…",
  "walletAddress": "0x7A3b…91cE",
  "ipRestriction": "203.0.113.10,203.0.113.11",
  "maxSpend": 5000.0,
  "totalSpend": 0.0,
  "remaining": 0,
  "lastUse": null,
  "createdAt": "2026-10-12T09:30:00Z"
}

key appears in this response only. walletAddress is the spender wallet: open the key in Settings → Remote Transfers and set its spending limit to grant the permission. Until you do, every transfer answers 403 No active spend permission for this API key.

Creating a key is refused with 403 in a session where a partner acts for your account. A key is a lasting credential, so only your own session can issue it. HEVN notifies you whenever a key is created.

List keys

curl "https://api.hevn.finance/api/v1/remote_spend_limit/api_key" \
  -H "Authorization: Bearer $HEVN_SESSION_TOKEN"

The response is an array, newest first. Each item has the fields above without key, plus keyPreview — the first eight and last four characters, such as rsl_Xk2a...9fQe.

Field	Meaning
totalSpend	USDC this key has sent, counted against maxSpend
remaining	The onchain allowance left after the key’s last transfer, in USDC base units (6 decimals). 0 until the first transfer. For a live figure, call GET /get_balance with the key
lastUse	When the key last sent a transfer

Revoke a key

Delete the key in Settings → Remote Transfers. The app revokes the spend permission onchain first, then deletes the key.

The API route deletes the key only:

curl -X DELETE "https://api.hevn.finance/api/v1/remote_spend_limit/api_key/$KEY_ID" \
  -H "Authorization: Bearer $HEVN_SESSION_TOKEN"

200 OK with {"ok": true}, or 404 API key not found. The deleted key stops authenticating at once, but the spend permission stays onchain until you revoke it. Revoke it in the app too, so no allowance is left pointing at a spender wallet nothing uses.

Keys do not expire. Deletion is permanent, and a deleted key cannot be restored — create a new one.

If a key leaks

1. Delete it in the app. That revokes its permission and kills the key in one action.
2. Create a new key with a new allowance.

The worst case before you act is bounded by what is left of the allowance in the current period, and by maxSpend if you set one.

Next: API reference

Every route a key can call, with fields, examples and errors.