Vault Endpoints - Renesis Docs

Vault Management Endpoints

This section covers all core vault management operations including CRUD operations, specialized queries, and vault configuration management.

POST /api/vaults

Create a new Stellar vault with specified configuration and ownership details.

Parameters

Request Body (JSON)

vaultName (string, required): Human-readable name for the vault (2-100 characters)
vaultOwner (string, required): Stellar address of the vault owner (must start with ‘G’, 56 characters)
vaultAddress (string, required): Stellar contract address of the vault (must start with ‘C’, 56 characters)
creationLedger (number, optional): Stellar ledger number when vault was created
tradePermission (boolean, optional): Whether trading is allowed (default: false)
maxTradeSize (number, optional): Maximum trade size as percentage of total vault value
dailyTradeLimit (number, optional): Number of trades allowed per day
slippageTolerance (number, optional): Slippage tolerance for swaps

Request Examples

Basic Vault Creation

curl -X POST "https://api.renesis.fi/api/vaults" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "vaultName": "DeFi Trading Vault",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationLedger": 123456789,
    "tradePermission": true,
    "maxTradeSize": 15,
    "dailyTradeLimit": 10,
    "slippageTolerance": 0.5
  }'

Storage-Only Vault Creation

curl -X POST "https://api.renesis.fi/api/vaults" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "vaultName": "Long-term Storage Vault",
    "vaultOwner": "GB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationLedger": 123456790,
    "tradePermission": false
  }'

High-Frequency Trading Vault

curl -X POST "https://api.renesis.fi/api/vaults" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "vaultName": "HFT Arbitrage Vault",
    "vaultOwner": "GC9QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CC9QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationLedger": 123456791,
    "tradePermission": true,
    "maxTradeSize": 25,
    "dailyTradeLimit": 50,
    "slippageTolerance": 0.1
  }'

Response Examples

Successful Vault Creation

{
  "success": true,
  "message": "Vault created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "vaultName": "DeFi Trading Vault",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationDate": "2024-01-15T10:30:00.000Z",
    "creationLedger": 123456789,
    "tradePermission": true,
    "maxTradeSize": 15,
    "dailyTradeLimit": 10,
    "slippageTolerance": 0.5,
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Storage Vault Creation Response

{
  "success": true,
  "message": "Storage vault created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439012",
    "vaultName": "Long-term Storage Vault",
    "vaultOwner": "GB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationDate": "2024-01-15T11:45:00.000Z",
    "creationLedger": 123456790,
    "tradePermission": false,
    "maxTradeSize": 0,
    "dailyTradeLimit": 0,
    "slippageTolerance": 1.0,
    "updatedAt": "2024-01-15T11:45:00.000Z",
    "createdAt": "2024-01-15T11:45:00.000Z"
  }
}

Error Responses

400 Bad Request - Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "vaultName",
      "message": "Vault name must be between 2 and 100 characters",
      "value": ""
    },
    {
      "field": "vaultOwner",
      "message": "Invalid Stellar address format",
      "value": "invalid-address"
    }
  ]
}

409 Conflict - Duplicate Vault

{
  "success": false,
  "message": "Vault with this address already exists",
  "errors": [
    {
      "field": "vaultAddress",
      "message": "Vault address must be unique",
      "value": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
    }
  ]
}

GET /api/vaults

Retrieve all vaults with optional filtering, pagination, and sorting capabilities.

Parameters

Query Parameters

page (number, optional): Page number for pagination (default: 1)
limit (number, optional): Number of items per page (default: 10, max: 100)
owner (string, optional): Filter by vault owner Stellar address
tradePermission (boolean, optional): Filter by trade permission status
search (string, optional): Search vault names (case-insensitive)
sortBy (string, optional): Sort field - creationDate, creationLedger, vaultName, updatedAt
sortOrder (string, optional): Sort order - asc or desc (default: desc)
minLedger (number, optional): Filter vaults created after this ledger number
maxLedger (number, optional): Filter vaults created before this ledger number

Request Example

curl -X GET "https://api.renesis.fi/api/vaults?page=1&limit=10&owner=GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ&tradePermission=true&sortBy=creationDate&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Vaults retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "vaultName": "My Trading Vault",
      "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "creationDate": "2024-01-15T10:30:00.000Z",
      "creationLedger": 123456789,
      "tradePermission": true,
      "maxTradeSize": 10,
      "dailyTradeLimit": 5,
      "slippageTolerance": 0.5,
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Error Responses

400 Bad Request - Invalid Parameters

{
  "success": false,
  "message": "Invalid query parameters",
  "errors": [
    {
      "field": "limit",
      "message": "Limit must be between 1 and 100",
      "value": 150
    }
  ]
}

GET /api/vaults/:id

Retrieve a specific vault by its unique identifier.

Parameters

Path Parameters

id (string, required): MongoDB ObjectId of the vault

Request Example

curl -X GET "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Vault retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "vaultName": "My Trading Vault",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationDate": "2024-01-15T10:30:00.000Z",
    "creationLedger": 123456789,
    "tradePermission": true,
    "maxTradeSize": 10,
    "dailyTradeLimit": 5,
    "slippageTolerance": 0.5,
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Error Responses

400 Bad Request - Invalid ID Format

{
  "success": false,
  "message": "Invalid vault ID format",
  "errors": [
    {
      "field": "id",
      "message": "Must be a valid MongoDB ObjectId",
      "value": "invalid-id"
    }
  ]
}

404 Not Found

{
  "success": false,
  "message": "Vault not found"
}

PUT /api/vaults/:id

Update an existing vault’s configuration and metadata.

Parameters

Path Parameters

id (string, required): MongoDB ObjectId of the vault

Request Body (JSON)

vaultName (string, optional): Updated vault name (2-100 characters)
tradePermission (boolean, optional): Updated trade permission status
maxTradeSize (number, optional): Updated maximum trade size percentage
dailyTradeLimit (number, optional): Updated daily trade limit
slippageTolerance (number, optional): Updated slippage tolerance

The vaultOwner and vaultAddress fields cannot be updated after vault creation for security reasons.

Request Example

curl -X PUT "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vaultName": "Updated Trading Vault",
    "tradePermission": false,
    "maxTradeSize": 15,
    "dailyTradeLimit": 10
  }'

Response Example

{
  "success": true,
  "message": "Vault updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "vaultName": "Updated Trading Vault",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationDate": "2024-01-15T10:30:00.000Z",
    "creationLedger": 123456789,
    "tradePermission": false,
    "maxTradeSize": 15,
    "dailyTradeLimit": 10,
    "slippageTolerance": 0.5,
    "updatedAt": "2024-01-15T11:45:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Error Responses

400 Bad Request - Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "maxTradeSize",
      "message": "Maximum trade size must be between 0 and 100",
      "value": 150
    }
  ]
}

404 Not Found

{
  "success": false,
  "message": "Vault not found"
}

DELETE /api/vaults/:id

Permanently delete a vault and all associated data.

Parameters

Path Parameters

id (string, required): MongoDB ObjectId of the vault

This operation is irreversible. All vault data and associated token holdings will be permanently deleted.

Request Example

curl -X DELETE "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Vault deleted successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "deletedAt": "2024-01-15T12:00:00.000Z"
  }
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "Vault not found"
}

400 Bad Request - Invalid ID Format

{
  "success": false,
  "message": "Invalid vault ID format",
  "errors": [
    {
      "field": "id",
      "message": "Must be a valid MongoDB ObjectId",
      "value": "invalid-id"
    }
  ]
}

GET /api/vaults/by-address/:address

Retrieve a vault by its Stellar contract address.

Parameters

Path Parameters

address (string, required): Stellar contract address of the vault (must start with ‘C’, 56 characters)

Request Example

curl -X GET "https://api.renesis.fi/api/vaults/by-address/CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Vault retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "vaultName": "My Trading Vault",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationDate": "2024-01-15T10:30:00.000Z",
    "creationLedger": 123456789,
    "tradePermission": true,
    "maxTradeSize": 10,
    "dailyTradeLimit": 5,
    "slippageTolerance": 0.5,
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Error Responses

400 Bad Request - Invalid Address Format

{
  "success": false,
  "message": "Invalid Stellar address format",
  "errors": [
    {
      "field": "address",
      "message": "Must be a valid Stellar contract address starting with 'C'",
      "value": "invalid-address"
    }
  ]
}

404 Not Found

{
  "success": false,
  "message": "Vault not found with the specified address"
}

GET /api/vaults/by-owner/:owner

Retrieve all vaults owned by a specific Stellar address.

Parameters

Path Parameters

owner (string, required): Stellar address of the vault owner (must start with ‘G’, 56 characters)

Query Parameters

page (number, optional): Page number for pagination (default: 1)
limit (number, optional): Number of items per page (default: 10, max: 100)
sortBy (string, optional): Sort field - creationDate, creationLedger, vaultName, updatedAt
sortOrder (string, optional): Sort order - asc or desc (default: desc)

Request Example

curl -X GET "https://api.renesis.fi/api/vaults/by-owner/GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ?page=1&limit=10&sortBy=creationDate&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Vaults retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "vaultName": "My Trading Vault",
      "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "creationDate": "2024-01-15T10:30:00.000Z",
      "creationLedger": 123456789,
      "tradePermission": true,
      "maxTradeSize": 10,
      "dailyTradeLimit": 5,
      "slippageTolerance": 0.5,
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "vaultName": "My Storage Vault",
      "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGX",
      "creationDate": "2024-01-14T09:15:00.000Z",
      "creationLedger": 123456788,
      "tradePermission": false,
      "maxTradeSize": 0,
      "dailyTradeLimit": 0,
      "slippageTolerance": 1.0,
      "updatedAt": "2024-01-14T09:15:00.000Z",
      "createdAt": "2024-01-14T09:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 2,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Error Responses

400 Bad Request - Invalid Owner Address

{
  "success": false,
  "message": "Invalid Stellar address format",
  "errors": [
    {
      "field": "owner",
      "message": "Must be a valid Stellar address starting with 'G'",
      "value": "invalid-owner"
    }
  ]
}

GET /api/vaults/trade-permission

Retrieve all vaults that have trading permissions enabled.

Parameters

Query Parameters

page (number, optional): Page number for pagination (default: 1)
limit (number, optional): Number of items per page (default: 10, max: 100)
owner (string, optional): Filter by specific vault owner Stellar address
sortBy (string, optional): Sort field - creationDate, creationLedger, vaultName, updatedAt
sortOrder (string, optional): Sort order - asc or desc (default: desc)

Request Example

curl -X GET "https://api.renesis.fi/api/vaults/trade-permission?page=1&limit=10&sortBy=creationDate&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Trade-enabled vaults retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "vaultName": "My Trading Vault",
      "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "creationDate": "2024-01-15T10:30:00.000Z",
      "creationLedger": 123456789,
      "tradePermission": true,
      "maxTradeSize": 10,
      "dailyTradeLimit": 5,
      "slippageTolerance": 0.5,
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Error Responses

400 Bad Request - Invalid Parameters

{
  "success": false,
  "message": "Invalid query parameters",
  "errors": [
    {
      "field": "limit",
      "message": "Limit must be between 1 and 100",
      "value": 150
    }
  ]
}

PATCH /api/vaults/:id/toggle-trade

Toggle the trade permission status for a specific vault.

Parameters

Path Parameters

id (string, required): MongoDB ObjectId of the vault

Request Body (JSON)

tradePermission (boolean, required): New trade permission status
maxTradeSize (number, optional): Maximum trade size percentage (required if enabling trading)
dailyTradeLimit (number, optional): Daily trade limit (required if enabling trading)
slippageTolerance (number, optional): Slippage tolerance for trades

Request Example

curl -X PATCH "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/toggle-trade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tradePermission": true,
    "maxTradeSize": 15,
    "dailyTradeLimit": 10,
    "slippageTolerance": 0.5
  }'

Response Example

{
  "success": true,
  "message": "Trade permission updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "vaultName": "My Trading Vault",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "creationDate": "2024-01-15T10:30:00.000Z",
    "creationLedger": 123456789,
    "tradePermission": true,
    "maxTradeSize": 15,
    "dailyTradeLimit": 10,
    "slippageTolerance": 0.5,
    "updatedAt": "2024-01-15T12:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Error Responses

400 Bad Request - Missing Required Fields

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "maxTradeSize",
      "message": "Max trade size is required when enabling trading",
      "value": null
    },
    {
      "field": "dailyTradeLimit",
      "message": "Daily trade limit is required when enabling trading",
      "value": null
    }
  ]
}

404 Not Found

{
  "success": false,
  "message": "Vault not found"
}

GET /api/vaults/stats

Retrieve comprehensive statistics about all vaults in the system.

Parameters

Query Parameters

owner (string, optional): Filter statistics by specific vault owner
tradePermission (boolean, optional): Filter by trade permission status
minLedger (number, optional): Include vaults created after this ledger
maxLedger (number, optional): Include vaults created before this ledger

Request Example

curl -X GET "https://api.renesis.fi/api/vaults/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Vault statistics retrieved successfully",
  "data": {
    "totalVaults": 150,
    "tradeEnabledVaults": 45,
    "tradeDisabledVaults": 105,
    "averageMaxTradeSize": 12.5,
    "averageDailyTradeLimit": 7.2,
    "averageSlippageTolerance": 0.75,
    "vaultsByCreationDate": {
      "last24Hours": 5,
      "last7Days": 23,
      "last30Days": 67,
      "last90Days": 120
    },
    "vaultsByLedgerRange": {
      "minLedger": 123400000,
      "maxLedger": 123500000,
      "averageLedger": 123456789
    },
    "topOwners": [
      {
        "owner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "vaultCount": 12,
        "tradeEnabledCount": 8
      },
      {
        "owner": "GB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "vaultCount": 9,
        "tradeEnabledCount": 3
      }
    ],
    "tradeSettings": {
      "maxTradeSize": {
        "min": 1,
        "max": 50,
        "average": 12.5,
        "median": 10
      },
      "dailyTradeLimit": {
        "min": 1,
        "max": 100,
        "average": 7.2,
        "median": 5
      },
      "slippageTolerance": {
        "min": 0.1,
        "max": 5.0,
        "average": 0.75,
        "median": 0.5
      }
    }
  }
}

Error Responses

400 Bad Request - Invalid Parameters

{
  "success": false,
  "message": "Invalid query parameters",
  "errors": [
    {
      "field": "minLedger",
      "message": "Minimum ledger must be a positive number",
      "value": -1
    }
  ]
}

TypeScript Interfaces

Core Vault Interface

interface Vault {
  id: string;                    // MongoDB ObjectId
  vaultName: string;             // Human-readable vault name (2-100 chars)
  vaultOwner: string;            // Stellar address (starts with 'G', 56 chars)
  vaultAddress: string;          // Stellar contract address (starts with 'C', 56 chars)
  creationDate: string;          // ISO 8601 timestamp
  creationLedger: number;        // Stellar ledger number
  tradePermission: boolean;      // Trading allowed flag
  maxTradeSize: number;          // Max trade size as percentage (0-100)
  dailyTradeLimit: number;       // Daily trade limit count
  slippageTolerance: number;     // Slippage tolerance for swaps (0-100)
  updatedAt: string;             // ISO 8601 timestamp
  createdAt: string;             // ISO 8601 timestamp
}

Request/Response Interfaces

// Create vault request
interface CreateVaultRequest {
  vaultName: string;
  vaultOwner: string;
  vaultAddress: string;
  creationLedger?: number;
  tradePermission?: boolean;
  maxTradeSize?: number;
  dailyTradeLimit?: number;
  slippageTolerance?: number;
}

// Update vault request
interface UpdateVaultRequest {
  vaultName?: string;
  tradePermission?: boolean;
  maxTradeSize?: number;
  dailyTradeLimit?: number;
  slippageTolerance?: number;
}

// Toggle trade permission request
interface ToggleTradeRequest {
  tradePermission: boolean;
  maxTradeSize?: number;
  dailyTradeLimit?: number;
  slippageTolerance?: number;
}

// Vault statistics response
interface VaultStatsResponse {
  totalVaults: number;
  tradeEnabledVaults: number;
  tradeDisabledVaults: number;
  averageMaxTradeSize: number;
  averageDailyTradeLimit: number;
  averageSlippageTolerance: number;
  vaultsByCreationDate: {
    last24Hours: number;
    last7Days: number;
    last30Days: number;
    last90Days: number;
  };
  vaultsByLedgerRange: {
    minLedger: number;
    maxLedger: number;
    averageLedger: number;
  };
  topOwners: Array<{
    owner: string;
    vaultCount: number;
    tradeEnabledCount: number;
  }>;
  tradeSettings: {
    maxTradeSize: {
      min: number;
      max: number;
      average: number;
      median: number;
    };
    dailyTradeLimit: {
      min: number;
      max: number;
      average: number;
      median: number;
    };
    slippageTolerance: {
      min: number;
      max: number;
      average: number;
      median: number;
    };
  };
}

// API Response wrapper
interface APIResponse<T> {
  success: boolean;
  message: string;
  data?: T;
  pagination?: {
    page: number;
    limit: number;
    totalItems: number;
    totalPages: number;
    hasNext: boolean;
    hasPrev: boolean;
  };
}

// Query parameters for vault listing
interface VaultQueryParams {
  page?: number;
  limit?: number;
  owner?: string;
  tradePermission?: boolean;
  search?: string;
  sortBy?: 'creationDate' | 'creationLedger' | 'vaultName' | 'updatedAt';
  sortOrder?: 'asc' | 'desc';
  minLedger?: number;
  maxLedger?: number;
}

Example Data Objects

// Example vault object with realistic data
const exampleVault: Vault = {
  id: "507f1f77bcf86cd799439011",
  vaultName: "DeFi Trading Vault",
  vaultOwner: "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
  vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
  creationDate: "2024-01-15T10:30:00.000Z",
  creationLedger: 123456789,
  tradePermission: true,
  maxTradeSize: 15,
  dailyTradeLimit: 10,
  slippageTolerance: 0.5,
  updatedAt: "2024-01-15T14:22:30.000Z",
  createdAt: "2024-01-15T10:30:00.000Z"
};

// Example create vault request
const createVaultExample: CreateVaultRequest = {
  vaultName: "High-Yield Savings Vault",
  vaultOwner: "GB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
  vaultAddress: "CB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
  creationLedger: 123456790,
  tradePermission: false,
  maxTradeSize: 0,
  dailyTradeLimit: 0,
  slippageTolerance: 1.0
};

// Example vault statistics
const vaultStatsExample: VaultStatsResponse = {
  totalVaults: 1247,
  tradeEnabledVaults: 423,
  tradeDisabledVaults: 824,
  averageMaxTradeSize: 12.8,
  averageDailyTradeLimit: 6.4,
  averageSlippageTolerance: 0.73,
  vaultsByCreationDate: {
    last24Hours: 12,
    last7Days: 89,
    last30Days: 234,
    last90Days: 567
  },
  vaultsByLedgerRange: {
    minLedger: 123400000,
    maxLedger: 123500000,
    averageLedger: 123456789
  },
  topOwners: [
    {
      owner: "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      vaultCount: 23,
      tradeEnabledCount: 15
    },
    {
      owner: "GB8QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      vaultCount: 18,
      tradeEnabledCount: 7
    }
  ],
  tradeSettings: {
    maxTradeSize: {
      min: 1,
      max: 50,
      average: 12.8,
      median: 10
    },
    dailyTradeLimit: {
      min: 1,
      max: 100,
      average: 6.4,
      median: 5
    },
    slippageTolerance: {
      min: 0.1,
      max: 5.0,
      average: 0.73,
      median: 0.5
    }
  }
};

Validation Rules

Vault Name: 2-100 characters, required
Vault Owner: Valid Stellar address starting with ‘G’, 56 characters
Vault Address: Valid Stellar contract address starting with ‘C’, 56 characters, must be unique
Creation Ledger: Positive integer
Trade Permission: Boolean value
Max Trade Size: Number between 0-100 (percentage)
Daily Trade Limit: Positive integer
Slippage Tolerance: Number between 0-100 (percentage)

Common Use Cases

Creating a Basic Vault

curl -X POST "https://api.renesis.fi/api/vaults" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vaultName": "Basic Vault",
    "vaultOwner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
  }'

Finding Vaults by Owner

curl -X GET "https://api.renesis.fi/api/vaults?owner=GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ" \
  -H "Authorization: Bearer YOUR_API_KEY"

Enabling Trading for a Vault

curl -X PUT "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tradePermission": true,
    "maxTradeSize": 10,
    "dailyTradeLimit": 5
  }'

Finding a Vault by Address

curl -X GET "https://api.renesis.fi/api/vaults/by-address/CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ" \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting All Vaults for an Owner

curl -X GET "https://api.renesis.fi/api/vaults/by-owner/GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ" \
  -H "Authorization: Bearer YOUR_API_KEY"

Finding Trade-Enabled Vaults

curl -X GET "https://api.renesis.fi/api/vaults/trade-permission" \
  -H "Authorization: Bearer YOUR_API_KEY"

Toggling Trade Permission

curl -X PATCH "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/toggle-trade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tradePermission": true,
    "maxTradeSize": 15,
    "dailyTradeLimit": 10
  }'

Getting Vault Statistics

curl -X GET "https://api.renesis.fi/api/vaults/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Next Steps

Token Endpoints - Manage token holdings and balances
Search & Filtering - Advanced vault discovery
Error Handling - Error codes and troubleshooting

Getting Started

Vaults

Smart Contracts

Order Execution

Swap Infrastructure

Contract Addresses

API Reference

Disclaimers

​Vault Management Endpoints

​POST /api/vaults

​Parameters

​Request Examples

​Basic Vault Creation

​Storage-Only Vault Creation

​High-Frequency Trading Vault

​Response Examples

​Successful Vault Creation

​Storage Vault Creation Response

​Error Responses

​GET /api/vaults

​Parameters

​Request Example

​Response Example

​Error Responses

​GET /api/vaults/:id

​Parameters

​Request Example

​Response Example

​Error Responses

​PUT /api/vaults/:id

​Parameters

​Request Example

​Response Example

​Error Responses

​DELETE /api/vaults/:id

​Parameters

​Request Example

​Response Example

​Error Responses

​GET /api/vaults/by-address/:address

​Parameters

​Request Example

​Response Example

​Error Responses

​GET /api/vaults/by-owner/:owner

​Parameters

​Request Example

​Response Example

​Error Responses

​GET /api/vaults/trade-permission

​Parameters

​Request Example

​Response Example

​Error Responses

​PATCH /api/vaults/:id/toggle-trade

​Parameters

​Request Example

​Response Example

​Error Responses

​GET /api/vaults/stats

​Parameters

​Request Example

​Response Example

​Error Responses

​TypeScript Interfaces

​Core Vault Interface

​Request/Response Interfaces

​Example Data Objects

​Validation Rules

​Common Use Cases

​Creating a Basic Vault

​Finding Vaults by Owner

​Enabling Trading for a Vault

​Finding a Vault by Address

​Getting All Vaults for an Owner

​Finding Trade-Enabled Vaults

​Toggling Trade Permission

​Getting Vault Statistics

​Next Steps

Vault Management Endpoints

POST /api/vaults

Parameters

Request Examples

Basic Vault Creation

Storage-Only Vault Creation

High-Frequency Trading Vault

Response Examples

Successful Vault Creation

Storage Vault Creation Response

Error Responses

GET /api/vaults

Parameters

Request Example

Response Example

Error Responses

GET /api/vaults/:id

Parameters

Request Example

Response Example

Error Responses

PUT /api/vaults/:id

Parameters

Request Example

Response Example

Error Responses

DELETE /api/vaults/:id

Parameters

Request Example

Response Example

Error Responses

GET /api/vaults/by-address/:address

Parameters

Request Example

Response Example

Error Responses

GET /api/vaults/by-owner/:owner

Parameters

Request Example

Response Example

Error Responses

GET /api/vaults/trade-permission

Parameters

Request Example

Response Example

Error Responses

PATCH /api/vaults/:id/toggle-trade

Parameters

Request Example

Response Example

Error Responses

GET /api/vaults/stats

Parameters

Request Example

Response Example

Error Responses

TypeScript Interfaces

Core Vault Interface

Request/Response Interfaces

Example Data Objects

Validation Rules

Common Use Cases

Creating a Basic Vault

Finding Vaults by Owner

Enabling Trading for a Vault

Finding a Vault by Address

Getting All Vaults for an Owner

Finding Trade-Enabled Vaults

Toggling Trade Permission

Getting Vault Statistics

Next Steps