Token Endpoints - Renesis Docs

Token Holdings Management Endpoints

This section covers all token holdings management operations including balance tracking, updates, and bulk operations across both testnet and mainnet Stellar networks.

Overview

The token holdings system provides real-time balance tracking for Stellar vaults across multiple tokens and networks. All token operations support both testnet and mainnet environments with automatic network detection and validation.

Key Features

Real-time Balance Updates: Direct integration with Stellar network for accurate balance fetching
Multi-Network Support: Seamless operation across testnet and mainnet
Bulk Operations: Efficient batch updates for multiple vaults
Token Validation: Automatic validation against supported token lists
Balance History: Track balance changes over time

Supported Networks

Testnet: Development and testing environment with test tokens
Mainnet: Production environment with live tokens and assets

POST /api/vaults/:id/update-holdings

Update token holdings for a specific vault by fetching current balances from the Stellar network.

Parameters

Path Parameters

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

Query Parameters

network (string, optional): Target Stellar network - testnet or mainnet (default: mainnet)

Request Body (JSON)

tokens (array, optional): Specific token contracts to update (if omitted, updates all supported tokens)
forceUpdate (boolean, optional): Force update even if recently updated (default: false)

Request Examples

Update All Supported Tokens (Mainnet)

curl -X POST "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/update-holdings?network=mainnet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "forceUpdate": false
  }'

Update Specific Tokens (Mainnet)

curl -X POST "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/update-holdings?network=mainnet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "tokens": [
      "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
      "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
      "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64"
    ],
    "forceUpdate": false
  }'

Force Update for Real-time Trading (Mainnet)

curl -X POST "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/update-holdings?network=mainnet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "tokens": [
      "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ"
    ],
    "forceUpdate": true
  }'

Update Holdings on Testnet

curl -X POST "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/update-holdings?network=testnet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -d '{
    "tokens": [
      "CTEST1TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD",
      "CTEST2TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD"
    ],
    "forceUpdate": false
  }'

Response Examples

Successful Holdings Update (Multiple Tokens)

{
  "success": true,
  "message": "Token holdings updated successfully",
  "data": {
    "vaultId": "507f1f77bcf86cd799439011",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "network": "mainnet",
    "updatedTokens": 3,
    "totalTokens": 5,
    "lastUpdated": "2024-01-15T14:30:00.000Z",
    "holdings": [
      {
        "id": "507f1f77bcf86cd799439013",
        "vaultId": "507f1f77bcf86cd799439011",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "tokenId": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
        "tokenSymbol": "XLM",
        "tokenName": "Stellar Lumens",
        "tokenContract": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
        "balance": "15420.0000000",
        "decimal": 7,
        "lastUpdated": "2024-01-15T14:30:00.000Z"
      },
      {
        "id": "507f1f77bcf86cd799439014",
        "vaultId": "507f1f77bcf86cd799439011",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "tokenId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
        "tokenSymbol": "USDC",
        "tokenName": "USD Coin",
        "tokenContract": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
        "balance": "2847.5000000",
        "decimal": 7,
        "lastUpdated": "2024-01-15T14:30:00.000Z"
      },
      {
        "id": "507f1f77bcf86cd799439015",
        "vaultId": "507f1f77bcf86cd799439011",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "tokenId": "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64",
        "tokenSymbol": "AQUA",
        "tokenName": "Aquarius",
        "tokenContract": "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64",
        "balance": "1250.7500000",
        "decimal": 7,
        "lastUpdated": "2024-01-15T14:30:00.000Z"
      }
    ]
  }
}

Single Token Update Response

{
  "success": true,
  "message": "USDC holdings updated successfully",
  "data": {
    "vaultId": "507f1f77bcf86cd799439011",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "network": "mainnet",
    "updatedTokens": 1,
    "totalTokens": 5,
    "lastUpdated": "2024-01-15T14:35:00.000Z",
    "holdings": [
      {
        "id": "507f1f77bcf86cd799439014",
        "vaultId": "507f1f77bcf86cd799439011",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "tokenId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
        "tokenSymbol": "USDC",
        "tokenName": "USD Coin",
        "tokenContract": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
        "balance": "2851.2500000",
        "decimal": 7,
        "lastUpdated": "2024-01-15T14:35:00.000Z"
      }
    ]
  }
}

Testnet Holdings Update Response

{
  "success": true,
  "message": "Testnet token holdings updated successfully",
  "data": {
    "vaultId": "507f1f77bcf86cd799439011",
    "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "network": "testnet",
    "updatedTokens": 2,
    "totalTokens": 3,
    "lastUpdated": "2024-01-15T14:40:00.000Z",
    "holdings": [
      {
        "id": "507f1f77bcf86cd799439016",
        "vaultId": "507f1f77bcf86cd799439011",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "tokenId": "CTEST1TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD",
        "tokenSymbol": "TEST1",
        "tokenName": "Test Token 1",
        "tokenContract": "CTEST1TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD",
        "balance": "10000.0000000",
        "decimal": 7,
        "lastUpdated": "2024-01-15T14:40:00.000Z"
      },
      {
        "id": "507f1f77bcf86cd799439017",
        "vaultId": "507f1f77bcf86cd799439011",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "tokenId": "CTEST2TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD",
        "tokenSymbol": "TEST2",
        "tokenName": "Test Token 2",
        "tokenContract": "CTEST2TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD",
        "balance": "5000.0000000",
        "decimal": 7,
        "lastUpdated": "2024-01-15T14:40:00.000Z"
      }
    ]
  }
}

Error Responses

400 Bad Request - Invalid Vault ID

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

400 Bad Request - Invalid Network

{
  "success": false,
  "message": "Invalid network parameter",
  "errors": [
    {
      "field": "network",
      "message": "Network must be 'testnet' or 'mainnet'",
      "value": "invalid-network"
    }
  ]
}

404 Not Found - Vault Not Found

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

400 Bad Request - Unsupported Token

{
  "success": false,
  "message": "Unsupported token contracts",
  "errors": [
    {
      "field": "tokens",
      "message": "Token contract not supported on mainnet",
      "value": "INVALID_TOKEN_CONTRACT"
    }
  ]
}

GET /api/vaults/:id/holdings

Retrieve current token holdings for a specific vault with optional filtering and pagination.

Parameters

Path Parameters

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

Query Parameters

page (number, optional): Page number for pagination (default: 1)
limit (number, optional): Number of items per page (default: 10, max: 100)
tokenSymbol (string, optional): Filter by specific token symbol (e.g., “USDC”, “XLM”)
minBalance (number, optional): Filter holdings with balance greater than this amount
maxBalance (number, optional): Filter holdings with balance less than this amount
sortBy (string, optional): Sort field - balance, tokenSymbol, lastUpdated (default: balance)
sortOrder (string, optional): Sort order - asc or desc (default: desc)
includeZeroBalances (boolean, optional): Include tokens with zero balance (default: false)

Request Example

curl -X GET "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/holdings?page=1&limit=10&minBalance=100&sortBy=balance&sortOrder=desc&includeZeroBalances=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Token holdings retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439013",
      "vaultId": "507f1f77bcf86cd799439011",
      "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "tokenId": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
      "tokenSymbol": "XLM",
      "tokenName": "Stellar Lumens",
      "tokenContract": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
      "balance": "5000.0000000",
      "decimal": 7,
      "lastUpdated": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439014",
      "vaultId": "507f1f77bcf86cd799439011",
      "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "tokenId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
      "tokenSymbol": "USDC",
      "tokenName": "USD Coin",
      "tokenContract": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
      "balance": "1250.5000000",
      "decimal": 7,
      "lastUpdated": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439015",
      "vaultId": "507f1f77bcf86cd799439011",
      "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      "tokenId": "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64",
      "tokenSymbol": "AQUA",
      "tokenName": "Aquarius",
      "tokenContract": "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64",
      "balance": "750.2500000",
      "decimal": 7,
      "lastUpdated": "2024-01-15T10:25:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 3,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Error Responses

400 Bad Request - Invalid Vault ID

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

404 Not Found - Vault Not Found

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

400 Bad Request - Invalid Parameters

{
  "success": false,
  "message": "Invalid query parameters",
  "errors": [
    {
      "field": "minBalance",
      "message": "Minimum balance must be a positive number",
      "value": -100
    }
  ]
}

POST /api/vaults/update-all-holdings

Bulk operation to update token holdings for multiple vaults simultaneously.

Parameters

Query Parameters

network (string, optional): Target Stellar network - testnet or mainnet (default: mainnet)
batchSize (number, optional): Number of vaults to process per batch (default: 10, max: 50)

Request Body (JSON)

vaultIds (array, optional): Specific vault IDs to update (if omitted, updates all vaults)
tokens (array, optional): Specific token contracts to update (if omitted, updates all supported tokens)
forceUpdate (boolean, optional): Force update even if recently updated (default: false)
owner (string, optional): Update only vaults owned by this Stellar address
tradePermissionOnly (boolean, optional): Update only vaults with trade permission enabled (default: false)

Request Example

curl -X POST "https://api.renesis.fi/api/vaults/update-all-holdings?network=mainnet&batchSize=20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vaultIds": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012",
      "507f1f77bcf86cd799439013"
    ],
    "tokens": [
      "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
      "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA"
    ],
    "forceUpdate": false,
    "tradePermissionOnly": true
  }'

Response Example

{
  "success": true,
  "message": "Bulk token holdings update completed",
  "data": {
    "network": "mainnet",
    "batchSize": 20,
    "totalVaultsProcessed": 3,
    "totalVaultsUpdated": 3,
    "totalVaultsFailed": 0,
    "totalTokensUpdated": 6,
    "processingTime": "2.5s",
    "startTime": "2024-01-15T10:30:00.000Z",
    "endTime": "2024-01-15T10:30:02.500Z",
    "results": [
      {
        "vaultId": "507f1f77bcf86cd799439011",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "status": "success",
        "tokensUpdated": 2,
        "lastUpdated": "2024-01-15T10:30:01.000Z"
      },
      {
        "vaultId": "507f1f77bcf86cd799439012",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGX",
        "status": "success",
        "tokensUpdated": 2,
        "lastUpdated": "2024-01-15T10:30:01.500Z"
      },
      {
        "vaultId": "507f1f77bcf86cd799439013",
        "vaultAddress": "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGY",
        "status": "success",
        "tokensUpdated": 2,
        "lastUpdated": "2024-01-15T10:30:02.000Z"
      }
    ],
    "summary": {
      "successRate": "100%",
      "averageTokensPerVault": 2,
      "averageProcessingTimePerVault": "0.83s"
    }
  }
}

Error Responses

400 Bad Request - Invalid Parameters

{
  "success": false,
  "message": "Invalid request parameters",
  "errors": [
    {
      "field": "batchSize",
      "message": "Batch size must be between 1 and 50",
      "value": 100
    }
  ]
}

400 Bad Request - Invalid Vault IDs

{
  "success": false,
  "message": "Invalid vault IDs provided",
  "errors": [
    {
      "field": "vaultIds",
      "message": "Invalid MongoDB ObjectId format",
      "value": "invalid-vault-id"
    }
  ]
}

207 Multi-Status - Partial Success

{
  "success": true,
  "message": "Bulk update completed with some failures",
  "data": {
    "network": "mainnet",
    "totalVaultsProcessed": 3,
    "totalVaultsUpdated": 2,
    "totalVaultsFailed": 1,
    "results": [
      {
        "vaultId": "507f1f77bcf86cd799439011",
        "status": "success",
        "tokensUpdated": 2
      },
      {
        "vaultId": "507f1f77bcf86cd799439012",
        "status": "success",
        "tokensUpdated": 2
      },
      {
        "vaultId": "507f1f77bcf86cd799439013",
        "status": "failed",
        "error": "Vault address not found on Stellar network",
        "tokensUpdated": 0
      }
    ]
  }
}

Supported Token Lists

The API maintains curated lists of supported tokens for each network environment.

Mainnet Supported Tokens

Major Tokens

XLM (Stellar Lumens): CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA
USDC (USD Coin): CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ
USDT (Tether USD): CCFCXDCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCFCF
AQUA (Aquarius): CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64
yXLM (Ultra Stellar): CDKLFZLJLWEO6Y7CCNITMB262N4JWFZR2KOQVUUQRXHX2RGG2BGXOZJM

DeFi Tokens

MOBI (Mobius): CD25MNVTZDL4Y3XBCPCJXGXATV5WUHHOWMYFF4YBEGU5FCPGMYTVG5JY
RMT (SureRemit): CDBLRD2XOHRPX7KQJC4VDCQQ7KGTLYILLO2BKDQCQX7KQJC4VDCQQ7KG
TERN (Ternio): CDGQCSAFWECEQRCQD6QCHSQBJA3DKDQCQX7KQJC4VDCQQ7KGTLYILLO

Stablecoins

EURT (Euro Tether): CEURT6TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD
ARST (ARST): CARST6TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD

Testnet Supported Tokens

Test Tokens

XLM (Test Lumens): CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA
USDC (Test USD Coin): CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ
TEST1 (Test Token 1): CTEST1TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD
TEST2 (Test Token 2): CTEST2TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD

Development Tokens

DEV (Development Token): CDEV6TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD
MOCK (Mock Token): CMOCK6TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD

Token List Updates

Token lists are regularly updated to include new supported assets. To request addition of new tokens:

Mainnet Tokens: Must be established tokens with sufficient liquidity and community adoption
Testnet Tokens: Development and testing tokens for integration purposes
Validation: All tokens undergo security and compatibility validation
Network Compatibility: Tokens must be compatible with Stellar network standards

TypeScript Interfaces

Core TokenHolding Interface

interface TokenHolding {
  id: string;                    // MongoDB ObjectId
  vaultId: string;               // Reference to vault ObjectId
  vaultAddress: string;          // Stellar contract address of vault
  tokenId: string;               // Stellar token contract address
  tokenSymbol: string;           // Token symbol (e.g., "USDC", "XLM")
  tokenName: string;             // Full token name (e.g., "USD Coin")
  tokenContract: string;         // Stellar contract address of token
  balance: string;               // Token balance as string (preserves precision)
  decimal: number;               // Token decimal places
  lastUpdated: string;           // ISO 8601 timestamp of last balance update
}

Request/Response Interfaces

// Update holdings request
interface UpdateHoldingsRequest {
  tokens?: string[];             // Specific token contracts to update
  forceUpdate?: boolean;         // Force update even if recently updated
}

// Bulk update request
interface BulkUpdateRequest {
  vaultIds?: string[];           // Specific vault IDs to update
  tokens?: string[];             // Specific token contracts to update
  forceUpdate?: boolean;         // Force update even if recently updated
  owner?: string;                // Update only vaults owned by this address
  tradePermissionOnly?: boolean; // Update only trade-enabled vaults
}

// Update holdings response
interface UpdateHoldingsResponse {
  vaultId: string;
  vaultAddress: string;
  network: string;
  updatedTokens: number;
  totalTokens: number;
  lastUpdated: string;
  holdings: TokenHolding[];
}

// Bulk update response
interface BulkUpdateResponse {
  network: string;
  batchSize: number;
  totalVaultsProcessed: number;
  totalVaultsUpdated: number;
  totalVaultsFailed: number;
  totalTokensUpdated: number;
  processingTime: string;
  startTime: string;
  endTime: string;
  results: VaultUpdateResult[];
  summary: {
    successRate: string;
    averageTokensPerVault: number;
    averageProcessingTimePerVault: string;
  };
}

interface VaultUpdateResult {
  vaultId: string;
  vaultAddress: string;
  status: 'success' | 'failed';
  tokensUpdated: number;
  lastUpdated?: string;
  error?: string;
}

// Token holdings query parameters
interface HoldingsQueryParams {
  page?: number;
  limit?: number;
  tokenSymbol?: string;
  minBalance?: number;
  maxBalance?: number;
  sortBy?: 'balance' | 'tokenSymbol' | 'lastUpdated';
  sortOrder?: 'asc' | 'desc';
  includeZeroBalances?: boolean;
}

// Supported token definition
interface SupportedToken {
  symbol: string;
  name: string;
  contract: string;
  decimal: number;
  network: 'testnet' | 'mainnet';
  category: 'major' | 'defi' | 'stablecoin' | 'test' | 'development';
}

Example Data Objects

// Example token holding with realistic data
const exampleTokenHolding: TokenHolding = {
  id: "507f1f77bcf86cd799439013",
  vaultId: "507f1f77bcf86cd799439011",
  vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
  tokenId: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
  tokenSymbol: "USDC",
  tokenName: "USD Coin",
  tokenContract: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
  balance: "2847.5000000",
  decimal: 7,
  lastUpdated: "2024-01-15T14:30:00.000Z"
};

// Example multiple token holdings
const exampleTokenHoldings: TokenHolding[] = [
  {
    id: "507f1f77bcf86cd799439013",
    vaultId: "507f1f77bcf86cd799439011",
    vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    tokenId: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    tokenSymbol: "XLM",
    tokenName: "Stellar Lumens",
    tokenContract: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    balance: "15420.0000000",
    decimal: 7,
    lastUpdated: "2024-01-15T14:30:00.000Z"
  },
  {
    id: "507f1f77bcf86cd799439014",
    vaultId: "507f1f77bcf86cd799439011",
    vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    tokenId: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
    tokenSymbol: "USDC",
    tokenName: "USD Coin",
    tokenContract: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
    balance: "2847.5000000",
    decimal: 7,
    lastUpdated: "2024-01-15T14:30:00.000Z"
  },
  {
    id: "507f1f77bcf86cd799439015",
    vaultId: "507f1f77bcf86cd799439011",
    vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    tokenId: "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64",
    tokenSymbol: "AQUA",
    tokenName: "Aquarius",
    tokenContract: "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64",
    balance: "1250.7500000",
    decimal: 7,
    lastUpdated: "2024-01-15T14:25:00.000Z"
  }
];

// Example bulk update response
const exampleBulkUpdateResponse: BulkUpdateResponse = {
  network: "mainnet",
  batchSize: 20,
  totalVaultsProcessed: 15,
  totalVaultsUpdated: 14,
  totalVaultsFailed: 1,
  totalTokensUpdated: 42,
  processingTime: "8.7s",
  startTime: "2024-01-15T14:30:00.000Z",
  endTime: "2024-01-15T14:30:08.700Z",
  results: [
    {
      vaultId: "507f1f77bcf86cd799439011",
      vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
      status: "success",
      tokensUpdated: 3,
      lastUpdated: "2024-01-15T14:30:02.100Z"
    },
    {
      vaultId: "507f1f77bcf86cd799439012",
      vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGX",
      status: "success",
      tokensUpdated: 2,
      lastUpdated: "2024-01-15T14:30:03.500Z"
    },
    {
      vaultId: "507f1f77bcf86cd799439013",
      vaultAddress: "CA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGY",
      status: "failed",
      tokensUpdated: 0,
      error: "Vault address not found on Stellar network"
    }
  ],
  summary: {
    successRate: "93.3%",
    averageTokensPerVault: 3.0,
    averageProcessingTimePerVault: "0.58s"
  }
};

// Example supported tokens
const supportedTokensMainnet: SupportedToken[] = [
  {
    symbol: "XLM",
    name: "Stellar Lumens",
    contract: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    decimal: 7,
    network: "mainnet",
    category: "major"
  },
  {
    symbol: "USDC",
    name: "USD Coin",
    contract: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
    decimal: 7,
    network: "mainnet",
    category: "stablecoin"
  },
  {
    symbol: "AQUA",
    name: "Aquarius",
    contract: "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJPKQ3CWBJ2WQXKWBCPO64",
    decimal: 7,
    network: "mainnet",
    category: "defi"
  }
];

const supportedTokensTestnet: SupportedToken[] = [
  {
    symbol: "XLM",
    name: "Test Lumens",
    contract: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
    decimal: 7,
    network: "testnet",
    category: "test"
  },
  {
    symbol: "USDC",
    name: "Test USD Coin",
    contract: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ",
    decimal: 7,
    network: "testnet",
    category: "test"
  },
  {
    symbol: "DEV",
    name: "Development Token",
    contract: "CDEV6TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD",
    decimal: 7,
    network: "testnet",
    category: "development"
  }
];

Bulk Update Response Interface

interface BulkUpdateResponse {
  network: string;               // Target network (testnet/mainnet)
  batchSize: number;             // Configured batch size
  totalVaultsProcessed: number;  // Total vaults processed
  totalVaultsUpdated: number;    // Successfully updated vaults
  totalVaultsFailed: number;     // Failed vault updates
  totalTokensUpdated: number;    // Total token holdings updated
  processingTime: string;        // Total processing time
  startTime: string;             // Process start timestamp
  endTime: string;               // Process end timestamp
  results: VaultUpdateResult[];  // Individual vault results
  summary: {
    successRate: string;         // Success percentage
    averageTokensPerVault: number;
    averageProcessingTimePerVault: string;
  };
}

interface VaultUpdateResult {
  vaultId: string;               // Vault ObjectId
  vaultAddress: string;          // Vault Stellar address
  status: 'success' | 'failed';  // Update status
  tokensUpdated: number;         // Number of tokens updated
  lastUpdated?: string;          // Update timestamp (if successful)
  error?: string;                // Error message (if failed)
}

Common Use Cases

Update Holdings for Single Vault (Mainnet)

curl -X POST "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/update-holdings?network=mainnet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "forceUpdate": true
  }'

Update Holdings for Single Vault (Testnet)

curl -X POST "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/update-holdings?network=testnet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tokens": ["CTEST1TCDJH6Q5MEGJLS3LNGKDNGK6RQCHSQBJA3DKDQCQX7KQJC4VD"]
  }'

Get Holdings with Filtering

curl -X GET "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/holdings?minBalance=100&tokenSymbol=USDC&sortBy=balance&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk Update All Trade-Enabled Vaults

curl -X POST "https://api.renesis.fi/api/vaults/update-all-holdings?network=mainnet" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tradePermissionOnly": true,
    "forceUpdate": false
  }'

Bulk Update Specific Vaults

curl -X POST "https://api.renesis.fi/api/vaults/update-all-holdings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "vaultIds": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012"
    ],
    "tokens": [
      "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAOBKYCYOEZ"
    ]
  }'

Update Holdings for Specific Owner

curl -X POST "https://api.renesis.fi/api/vaults/update-all-holdings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "owner": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
    "forceUpdate": true
  }'

Get Holdings Including Zero Balances

curl -X GET "https://api.renesis.fi/api/vaults/507f1f77bcf86cd799439011/holdings?includeZeroBalances=true&sortBy=tokenSymbol&sortOrder=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Performance Considerations

Rate Limiting

Token update operations are subject to rate limiting to prevent Stellar network overload
Bulk operations automatically implement batching to respect rate limits
Consider using forceUpdate: false to avoid unnecessary network calls

Caching Strategy

Token holdings are cached for 5 minutes by default
Use forceUpdate: true only when real-time accuracy is critical
Bulk operations optimize network calls by batching requests

Network Selection

Testnet: Faster response times, suitable for development and testing
Mainnet: Production environment with real assets, may have higher latency

Best Practices

Batch Updates: Use bulk operations for updating multiple vaults
Selective Updates: Specify token contracts to update only needed tokens
Pagination: Use appropriate page sizes for large holdings lists
Error Handling: Implement retry logic for network-related failures
Monitoring: Track update frequencies to optimize performance

Next Steps

Vault Endpoints - Core vault management operations
Search & Filtering - Advanced query capabilities
Error Handling - Error codes and troubleshooting

Getting Started

Vaults

Smart Contracts

Order Execution

Swap Infrastructure

Contract Addresses

API Reference

Disclaimers

​Token Holdings Management Endpoints

​Overview

​Key Features

​Supported Networks

​POST /api/vaults/:id/update-holdings

​Parameters

​Request Examples

​Update All Supported Tokens (Mainnet)

​Update Specific Tokens (Mainnet)

​Force Update for Real-time Trading (Mainnet)

​Update Holdings on Testnet

​Response Examples

​Successful Holdings Update (Multiple Tokens)

​Single Token Update Response

​Testnet Holdings Update Response

​Error Responses

​GET /api/vaults/:id/holdings

​Parameters

​Request Example

​Response Example

​Error Responses

​POST /api/vaults/update-all-holdings

​Parameters

​Request Example

​Response Example

​Error Responses

​Supported Token Lists

​Mainnet Supported Tokens

​Testnet Supported Tokens

​Token List Updates

​TypeScript Interfaces

​Core TokenHolding Interface

​Request/Response Interfaces

​Example Data Objects

​Bulk Update Response Interface

​Common Use Cases

​Update Holdings for Single Vault (Mainnet)

​Update Holdings for Single Vault (Testnet)

​Get Holdings with Filtering

​Bulk Update All Trade-Enabled Vaults

​Bulk Update Specific Vaults

​Update Holdings for Specific Owner

​Get Holdings Including Zero Balances

​Performance Considerations

​Rate Limiting

​Caching Strategy

​Network Selection

​Best Practices

​Next Steps

Token Holdings Management Endpoints

Overview

Key Features

Supported Networks

POST /api/vaults/:id/update-holdings

Parameters

Request Examples

Update All Supported Tokens (Mainnet)

Update Specific Tokens (Mainnet)

Force Update for Real-time Trading (Mainnet)

Update Holdings on Testnet

Response Examples

Successful Holdings Update (Multiple Tokens)

Single Token Update Response

Testnet Holdings Update Response

Error Responses

GET /api/vaults/:id/holdings

Parameters

Request Example

Response Example

Error Responses

POST /api/vaults/update-all-holdings

Parameters

Request Example

Response Example

Error Responses

Supported Token Lists

Mainnet Supported Tokens

Testnet Supported Tokens

Token List Updates

TypeScript Interfaces

Core TokenHolding Interface

Request/Response Interfaces

Example Data Objects

Bulk Update Response Interface

Common Use Cases

Update Holdings for Single Vault (Mainnet)

Update Holdings for Single Vault (Testnet)

Get Holdings with Filtering

Bulk Update All Trade-Enabled Vaults

Bulk Update Specific Vaults

Update Holdings for Specific Owner

Get Holdings Including Zero Balances

Performance Considerations

Rate Limiting

Caching Strategy

Network Selection

Best Practices

Next Steps