API Reference

Complete REST API and GraphQL documentation for zkVault Protocol

Base URL

Production:
https://api.vaultprotocol.ai
Testnet:
https://testnet-api.vaultprotocol.ai

Authentication

zkVault API uses wallet signature-based authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

// Or sign each request with wallet
X-Wallet-Address: 0x...
X-Signature: 0x...
X-Timestamp: 1234567890

Vault Endpoints

POST/api/vaultsAuth: Required

Create a new vault

Request Body:

{
  "name": "string",
  "releaseType": "SCHEDULED | DEADMAN | HYBRID",
  "unlockTime": "number (optional)",
  "checkInPeriod": "number (optional)",
  "recipients": "string[]",
  "encrypted": "boolean"
}

Response:

{
  "id": "string",
  "owner": "string",
  "createdAt": "timestamp"
}
GET/api/vaults/:idAuth: Required

Get vault details

Path Parameters:

id: Vault ID

Response:

{
  "id": "string",
  "name": "string",
  "releaseType": "string"
}
GET/api/vaultsAuth: Required

List vaults (paginated)

Query Parameters:

page: number, limit: number, owner: address (optional)

Response:

{
  "vaults": "Vault[]",
  "total": "number",
  "page": "number"
}
POST/api/vaults/:id/checkinAuth: Required

Perform vault check-in

Path Parameters:

id: Vault ID

Response:

{
  "success": "boolean",
  "nextCheckIn": "timestamp"
}
PUT/api/vaults/:id/beneficiariesAuth: Required

Update vault beneficiaries

Request Body:

{
  "beneficiaries": "[{ address, share }]"
}

Path Parameters:

id: Vault ID

Response:

{
  "success": "boolean",
  "beneficiaries": "Beneficiary[]"
}
POST/api/vaults/:id/releaseAuth: Required

Release vault assets

Path Parameters:

id: Vault ID

Response:

{
  "success": "boolean",
  "txHash": "string"
}

Attestation Endpoints

POST/api/attestationsAuth: Required

Submit death attestation

Request Body:

{
  "vaultId": "string",
  "proof": "string",
  "signatures": "string[]"
}

Response:

{
  "success": "boolean",
  "attestationId": "string"
}
GET/api/attestations/:vaultIdAuth: Optional

Get attestation status

Path Parameters:

vaultId: Vault ID

Response:

{
  "status": "string",
  "consensus": "number",
  "required": "number"
}

GraphQL API

Endpoint

POST https://api.vaultprotocol.ai/graphql

Example Query

query GetVault($id: ID!) {
  vault(id: $id) {
    id
    name
    owner
    releaseType
    unlockTime
    checkInPeriod
    recipients
    beneficiaries {
      address
      share
    }
    status
    createdAt
  }
}

Example Mutation

mutation CreateVault($input: CreateVaultInput!) {
  createVault(input: $input) {
    id
    owner
    name
    releaseType
    createdAt
  }
}

Example Subscription

subscription OnVaultUpdated($vaultId: ID!) {
  vaultUpdated(vaultId: $vaultId) {
    id
    status
    lastCheckIn
    updatedAt
  }
}

Rate Limits

100
Requests per minute
Free tier
1000
Requests per minute
Premium tier
Custom
Requests per minute
Enterprise tier

Rate Limit Headers: Check X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers in responses.

Common Error Codes

400
Bad Request
Invalid request parameters or body
401
Unauthorized
Missing or invalid authentication
403
Forbidden
Insufficient permissions for this resource
404
Not Found
Resource not found
429
Too Many Requests
Rate limit exceeded
500
Internal Server Error
Server error - contact support if persistent