Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/natureloved/DeadMan-Vault/llms.txt

Use this file to discover all available pages before exploring further.

The /api/heartbeat endpoint is the owner’s primary interaction surface with their vault. It handles two distinct lifecycle actions in a single route, selected by the action field in the request body. The heartbeat action lets a living vault owner prove presence — extending the on-chain lock so the vault never triggers. The claim action lets a registered beneficiary manually request their inheritance payout after a vault has been triggered by the keeper.
This endpoint can take up to 60 seconds to respond. Both actions wrap on-chain Stacks calls in retryWithBackoff, which polls until the owner’s check-in transfer confirms or the settlement finalises. Do not cancel the request early.

​
Endpoint

POST /api/heartbeat

​
Action: heartbeat

The heartbeat action is selected when action is "heartbeat" or is omitted entirely. Before calling this endpoint, the vault owner must send the minimum check-in amount (0.01 USDCx) to their vault’s keeper address from their own wallet. The fundingTxId of that transfer is then passed here so the keeper can verify confirmation and extend the lock. Internally, the keeper decrypts its private key for the vault, constructs a FlowVault instance, and:
  1. Reads the current Stacks block height.
  2. Calls FlowVault.setRoutingRules() with lockUntilBlock = currentBlock + heartbeatIntervalDays × 144.
  3. Calls FlowVault.deposit(HEARTBEAT_AMOUNT) to extend the lock via lock-stacking.
  4. Records the heartbeat in the database and updates the vault’s deadlineBlock.

​
Request Body

​
vaultId
string
required
The UUID of the vault to check in on. Must exist in the database and have a keeper key on file.
​
fundingTxId
string
required
The Stacks transaction ID of the owner’s 0.01 USDCx transfer to the vault keeper address. The endpoint retries until this transaction is confirmed on-chain.
​
action
string
Must be "heartbeat" or omitted. If omitted, the heartbeat action is assumed. Explicitly passing "heartbeat" is equivalent.

​
Response Fields

​
txId
string
The Stacks transaction ID of the on-chain deposit call that extended the vault lock.
​
newDeadlineBlock
number
The updated block height at which the vault will trigger if no further check-ins occur. Calculated as currentBlock + heartbeatIntervalDays × 144.

​
Example Request

curl --request POST \
  --url https://your-app.vercel.app/api/heartbeat \
  --header 'Content-Type: application/json' \
  --data '{
    "vaultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fundingTxId": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abc1",
    "action": "heartbeat"
  }'

​
Example Response

{
  "txId": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abc1",
  "newDeadlineBlock": 183024
}

​
Action: claim

The claim action is selected when action is explicitly "claim". It is intended for beneficiaries who want to manually initiate or retry their inheritance payout after the keeper has triggered a vault. The keeper cron attempts settlement automatically, so this action primarily serves as a manual retry path. Internally, the endpoint:
  1. Looks up the vault and verifies it is in triggered or claimed status.
  2. Verifies that beneficiaryAddress is registered as a beneficiary of the vault.
  3. Calls settleVaultPayout() if that beneficiary has not yet been paid.
  4. Re-fetches the beneficiary record and returns the confirmed claimed_tx_id.
If the payout transaction is still propagating, the endpoint returns a 400 error with "Payout is still processing — please try again in a moment." Retry after a short delay.

​
Request Body

​
vaultId
string
required
The UUID of the vault to claim from. The vault must be in triggered or claimed status.
​
beneficiaryAddress
string
required
The Stacks address of the beneficiary submitting the claim. Must be registered as a beneficiary on the specified vault.
​
action
string
required
Must be "claim".

​
Response Fields

​
txId
string
The Stacks transaction ID of the beneficiary’s payout transfer. Sourced from claimed_tx_id on the beneficiary record after settlement confirms.
​
amount
string
Reserved for the settled payout amount. Currently returns an empty string — amount tracking is not yet populated by the settlement layer.

​
Example Request

curl --request POST \
  --url https://your-app.vercel.app/api/heartbeat \
  --header 'Content-Type: application/json' \
  --data '{
    "vaultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "beneficiaryAddress": "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ",
    "action": "claim"
  }'

​
Example Response

{
  "txId": "0xdef789abc123def789abc123def789abc123def789abc123def789abc123def7",
  "amount": ""
}

​
Error Responses

StatusCondition
400fundingTxId is missing when action is "heartbeat" or omitted
400Vault not found for the provided vaultId
400Vault has no keeper account on file
400Vault has not been triggered (claim action on a non-triggered vault)
400beneficiaryAddress is not a registered beneficiary of the vault
400Payout is still processing — retry after a short delay
400action is set to an unrecognised value
All error responses follow the shape: 
{
  "error": "Human-readable error message"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us