GET /api/vaults/[id] — Fetch Complete Vault Details

Retrieves a single vault record by its UUID, including its full beneficiary list, complete heartbeat history (newest first), and — for vaults in an active lifecycle state — the current Stacks testnet block height fetched live from the Hiro API. The live block height lets clients compute time-to-deadline without a separate API call. It is omitted if the vault is in funding, triggered, or claimed status, or if the Hiro API is temporarily unavailable.

Endpoint

GET /api/vaults/{id}

Request Parameters

Path Parameters

string

required

The UUID of the vault to retrieve (e.g. a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c). Returns 404 if no vault with this ID exists.

Response

A JSON object combining the serialized vault fields, an optional current block height, the vault’s beneficiary records, and its heartbeat history.

Vault Fields

string

UUID of the vault record.

ownerAddress

string

Stacks address of the vault owner.

ownerEmail

string | null

Owner’s notification email, if set.

vaultName

string | null

Human-readable display name for the vault.

status

string

Current lifecycle state. One of funding, active, warning, grace_period, triggered, or claimed.

totalDeposited

string

USDCx amount locked in the vault, as a decimal string.

heartbeatIntervalDays

number

How many days are allowed between consecutive heartbeats.

lastHeartbeatBlock

number | null

Stacks block height of the most recent heartbeat. null before activation.

heartbeatDeadlineBlock

number | null

Block height by which the next heartbeat must arrive. null until the vault is active.

messageToBeneficiaries

string | null

Optional message shown to beneficiaries on the claim page.

txId

string | null

On-chain transaction ID of the FlowVault deposit call.

keeperAddress

string | null

Stacks address of the vault’s dedicated custodial keeper keypair.

currentBlock

number | undefined

Live Stacks testnet block height from the Hiro API. Present only when status is active, warning, or grace_period, and only when the Hiro API responds successfully. Use heartbeatDeadlineBlock - currentBlock to compute blocks remaining before the deadline.

createdAt

string

ISO 8601 timestamp of vault creation.

updatedAt

string

ISO 8601 timestamp of the last vault record modification.

Beneficiaries

beneficiaries

array

All beneficiary records associated with this vault.

Show Beneficiary fields

string

UUID of the beneficiary record.

vault_id

string

UUID of the parent vault.

address

string

Stacks address that receives the allocation on claim.

name

string

Display name for the beneficiary.

string | null

Notification email, if provided.

allocation_percent

number

Percentage of the vault balance allocated to this beneficiary.

vesting_days

number

Days after trigger before this beneficiary’s allocation is claimable.

vesting_release_at

string | null

ISO 8601 timestamp when the vesting period ends, set once the vault is triggered.

claimed

boolean

Whether this beneficiary has claimed their allocation.

claimed_at

string | null

ISO 8601 timestamp of when the claim was made.

claimed_tx_id

string | null

Transaction ID of the claim transfer, if claimed.

created_at

string

ISO 8601 timestamp of when the beneficiary record was created.

Heartbeats

heartbeats

array

All heartbeat records for this vault, ordered newest first.

Show Heartbeat fields

string

UUID of the heartbeat record.

vault_id

string

UUID of the parent vault.

block_height

number

The Stacks block height at which this heartbeat was recorded on-chain.

tx_id

string | null

Transaction ID of the on-chain heartbeat call, if applicable.

deposited_amount

string

USDCx amount in the vault at the time of this heartbeat.

created_at

string

ISO 8601 timestamp of when this heartbeat record was created.

If the Hiro API is unavailable when fetching currentBlock, the server logs the error and returns the vault response without a currentBlock value rather than returning a 500. Client code should treat an absent currentBlock as indeterminate.

Example Request

curl -X GET "https://your-app.vercel.app/api/vaults/a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c"

Example Response

{
  "id": "a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c",
  "ownerAddress": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM",
  "ownerEmail": "alice@example.com",
  "vaultName": "Family Trust",
  "status": "active",
  "totalDeposited": "500",
  "heartbeatIntervalDays": 90,
  "lastHeartbeatBlock": 148200,
  "heartbeatDeadlineBlock": 161160,
  "messageToBeneficiaries": "Please use these funds wisely.",
  "txId": "0xabc123def456...",
  "keeperAddress": "ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG",
  "currentBlock": 149830,
  "createdAt": "2024-11-01T09:15:00.000Z",
  "updatedAt": "2024-12-15T14:30:00.000Z",
  "beneficiaries": [
    {
      "id": "c1d2e3f4-5678-9abc-def0-1234567890ab",
      "vault_id": "a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c",
      "address": "ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG",
      "name": "Bob Smith",
      "email": "bob@example.com",
      "allocation_percent": 60,
      "vesting_days": 0,
      "vesting_release_at": null,
      "claimed": false,
      "claimed_at": null,
      "claimed_tx_id": null,
      "created_at": "2024-11-01T09:15:00.000Z"
    },
    {
      "id": "d2e3f4a5-6789-0bcd-ef01-23456789bcde",
      "vault_id": "a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c",
      "address": "ST3NBRSFKX28FQ2ZJ1MAKX58HKHSDGNV5YC7D3C5",
      "name": "Carol Smith",
      "email": "carol@example.com",
      "allocation_percent": 40,
      "vesting_days": 30,
      "vesting_release_at": null,
      "claimed": false,
      "claimed_at": null,
      "claimed_tx_id": null,
      "created_at": "2024-11-01T09:15:00.000Z"
    }
  ],
  "heartbeats": [
    {
      "id": "e3f4a5b6-789a-1cde-f012-3456789abcde",
      "vault_id": "a3f2c891-4b7e-4d3a-9c12-8f1e2d3a4b5c",
      "block_height": 148200,
      "tx_id": "0xdef789abc012...",
      "deposited_amount": "500",
      "created_at": "2024-12-15T14:30:00.000Z"
    }
  ]
}

Error Responses

Status	Error	Description
`404`	`Vault not found`	No vault record exists for the given `id`.
`500`	`Server misconfigured: missing Supabase env vars`	Required server-side environment variables are absent.

Vaults

Actions

GET /api/vaults/[id] — Fetch Complete Vault Details

Endpoint

Request Parameters

Path Parameters

Response

Vault Fields

Beneficiaries

Heartbeats

Example Request

Example Response

Error Responses

Build docs developers (and LLMs) love

Vaults

Actions

Documentation Index

​Endpoint

​Request Parameters

​Path Parameters

​Response

​Vault Fields

​Beneficiaries

​Heartbeats

​Example Request

​Example Response

​Error Responses

Build docs developers (and LLMs) love

Endpoint

Request Parameters

Path Parameters

Response

Vault Fields

Beneficiaries

Heartbeats

Example Request

Example Response

Error Responses