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.

Creates a new Deadman Vault record and provisions a dedicated custodial keeper keypair for it. The vault is initialized in funding status — it is not yet active on-chain. After this call completes, the owner must send the specified USDCx depositAmount to the returned keeperAddress, then call POST /api/vaults/{id}/fund with the resulting transaction ID to lock funds on-chain and start the heartbeat countdown.

​
Endpoint

POST /api/vaults

​
Request Parameters

​
Request Body

Send a JSON object with the following fields:
​
ownerAddress
string
required
The Stacks address of the vault owner (e.g. ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM). This address is stored as owner_address and used for all lifecycle queries.
​
depositAmount
string
required
The USDCx amount to lock in the vault, expressed as a decimal string (e.g. "100"). This value is stored as-is and passed to the FlowVault contract during the fund step.
​
heartbeatDays
number
required
The heartbeat interval in days. Must be between 7 and 730. If no heartbeat is received within this many days, the keeper begins advancing the vault toward triggered status.
​
beneficiaries
array
required
An array of beneficiary objects. The allocationPercent values across all entries must sum to exactly 100.
​
ownerEmail
string
Email address for the vault owner. Used to send heartbeat reminders and lifecycle alerts. Optional but strongly recommended.
​
message
string
An optional message displayed to beneficiaries on the claim page once the vault is triggered. Stored as message_to_beneficiaries.
​
vaultName
string
An optional human-readable name for the vault displayed in the dashboard (e.g. "Family Trust").

​
Response

Returns 201 Created with a JSON object containing the new vault’s ID and the keeper address to fund.
​
vaultId
string
The UUID of the newly created vault record. Use this in subsequent calls to GET /api/vaults/{id}, PATCH /api/vaults/{id}, and POST /api/vaults/{id}/fund.
​
keeperAddress
string
The Stacks address of the vault’s dedicated custodial keeper keypair. Send the depositAmount in USDCx to this address before calling the fund endpoint — the keeper uses the balance to call FlowVault.deposit() on-chain.
The vault will remain in funding status indefinitely until POST /api/vaults/{id}/fund is called with a valid txId. No heartbeat deadline is active during this period.
The beneficiary allocationPercent values must sum to exactly 100. The server rejects any request where the total differs, returning a 400 error.

​
Example Request

curl -X POST "https://your-app.vercel.app/api/vaults" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerAddress": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
    "ownerEmail": "alice@example.com",
    "depositAmount": "500",
    "heartbeatDays": 90,
    "vaultName": "Family Trust",
    "message": "Please use these funds wisely and take care of each other.",
    "beneficiaries": [
      {
        "address": "ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG",
        "name": "Bob Smith",
        "email": "bob@example.com",
        "allocationPercent": 60,
        "vestingDays": 0
      },
      {
        "address": "ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5YC7D3C5",
        "name": "Carol Smith",
        "email": "carol@example.com",
        "allocationPercent": 40,
        "vestingDays": 30
      }
    ]
  }'

​
Example Response

{
  "vaultId": "a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c",
  "keeperAddress": "ST4XQWRKC7NHDPWSXMW9QDT3HC3GD6Q6XX4ABCDE"
}

​
Error Responses

StatusErrorDescription
400Missing required fieldsOne or more of ownerAddress, depositAmount, or heartbeatDays was absent from the request body.
400Beneficiary allocations must total 100%Allocation percentages across all beneficiary entries did not sum to 100, or another validation rule (e.g. invalid beneficiary address) was violated during vault initialization.
500Server misconfigured: missing Supabase env varsRequired server-side environment variables are absent.

Build docs developers (and LLMs) love

Get started for freeTalk to us