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.

Finalizes the activation of a vault that is in funding status. After the owner sends the specified USDCx amount to the vault’s keeperAddress (obtained from POST /api/vaults), they call this endpoint with the transaction ID of that transfer. The server decrypts the keeper’s private key, calls FlowVault.setRoutingRules() to configure the lock parameters, then calls FlowVault.deposit() to lock the USDCx balance on-chain. Once confirmed, the vault’s database record is updated to active status with the recorded heartbeat baseline and deadline block.

​
Endpoint

POST /api/vaults/{id}/fund
This route has a maxDuration of 60 seconds. On-chain confirmation retries via retryWithBackoff can take up to ~40 seconds while waiting for the owner’s funding transfer to confirm on the Stacks testnet.

​
Request Parameters

​
Path Parameters

​
id
string
required
The UUID of the vault to activate. The vault must be in funding status or already active (idempotent — returns the existing activation data). Any other status throws an error and returns 400.

​
Request Body

​
txId
string
required
The transaction ID of the USDCx transfer the owner sent to the vault’s keeperAddress (e.g. 0xabc123def456...). The server uses this to verify the on-chain balance before proceeding with the FlowVault deposit call.

​
Response

Returns 200 OK with a JSON object confirming the on-chain activation.
​
vaultId
string
UUID of the vault that was activated.
​
txId
string
The transaction ID of the FlowVault.deposit() call submitted by the keeper. Store this value — it is saved to the vault record as the canonical deposit txId.
​
currentBlock
number
The Stacks block height at the time the deposit was confirmed on-chain. This becomes the vault’s lastHeartbeatBlock baseline.
​
deadlineBlock
number
The block height by which the first heartbeat must arrive, calculated as:
deadlineBlock = currentBlock + (heartbeatIntervalDays × 144)
144 blocks per day approximates the Stacks block time of ~10 minutes. This value is stored as heartbeat_deadline_block in the vault record.

​
Activation Flow

The following steps occur server-side when this endpoint is called:
  1. Fetch vault — Load the vault from the database and check its status. If already active, immediately return the existing vaultId, txId, currentBlock, and deadlineBlock (idempotent). Reject with 400 if the status is neither funding nor active.
  2. Decrypt keeper key — Decrypt keeper_key_ciphertext from the vault record to recover the keeper’s Stacks private key.
  3. Set routing rules — Call FlowVault.setRoutingRules() with the lock amount and the calculated deadline block.
  4. Deposit — Call FlowVault.deposit() using the keeper keypair to lock the USDCx balance on-chain. Uses retryWithBackoff to retry until the funding transfer confirms.
  5. Update DB — Set vault status to active, record lastHeartbeatBlock, heartbeatDeadlineBlock, and txId in the vault row.
If the USDCx transfer to keeperAddress has not yet confirmed on-chain when this endpoint is called, the server will retry with exponential back-off for up to ~40 seconds before failing. Ensure the funding transfer has at least one confirmation before calling this endpoint to reduce latency.

​
Example Request

curl -X POST "https://your-app.vercel.app/api/vaults/a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c/fund" \
  -H "Content-Type: application/json" \
  -d '{
    "txId": "0xabc123def456789..."
  }'

​
Example Response

{
  "vaultId": "a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c",
  "txId": "0xdef789abc012345...",
  "currentBlock": 148200,
  "deadlineBlock": 161160
}
In this example, heartbeatIntervalDays is 90. The deadline is calculated as 148200 + (90 × 144) = 161160.

​
Error Responses

StatusErrorDescription
400Missing funding transaction ID — send the transfer to the keeper address firstThe txId field was absent from the request body.
400Vault is in unexpected status "X" to be funded.The vault’s current status is not funding (e.g. warning, grace_period, triggered, or claimed). Only funding vaults can be activated; an already-active vault returns 200 idempotently instead of this error.
400Error message from finalizeVaultFundingThe on-chain transfer could not be verified after all retries, or another error occurred during the FlowVault contract calls. The full error message is returned verbatim.

Build docs developers (and LLMs) love

Get started for freeTalk to us