Skip to content
Shield FinanceShield Finance

API Reference

Shield Yield Vaults provides a RESTful API for managing vaults, positions, and transactions.

Base URL

Section titled “Base URL”
Development: http://localhost:5000/api
Production: https://shyield.finance/api

Authentication

Section titled “Authentication”

The API uses session-based authentication with wallet addresses. No API keys required for public endpoints.

Wallet-Scoped Access: All transaction endpoints require a walletAddress parameter. This ensures users can only access their own transaction data, providing privacy and security.

Endpoints Overview

Section titled “Endpoints Overview”

Vaults

Section titled “Vaults”
  • GET /api/vaults - List all vaults
  • GET /api/vaults/:id - Get vault details
  • GET /api/vaults/:id/metrics - Get vault metrics

Positions

Section titled “Positions”
  • GET /api/positions - List user positions
  • POST /api/positions/deposit - Create deposit
  • POST /api/positions/withdraw - Create withdrawal
  • POST /api/positions/:id/claim - Claim rewards

Transactions

Section titled “Transactions”
  • GET /api/transactions?walletAddress=<address> - List wallet-scoped transactions (REQUIRED parameter)
  • GET /api/transactions/summary?walletAddress=<address> - Get transaction summary (REQUIRED parameter)

Wallet

Section titled “Wallet”
  • POST /api/wallet/xaman/payload - Create Xaman sign-in payload
  • POST /api/wallet/xaman/deposit - Create deposit payload
  • POST /api/wallet/xaman/withdraw - Create withdrawal payload
  • POST /api/wallet/xaman/claim - Create claim payload
  • GET /api/wallet/xaman/status/:uuid - Check payload status
  • POST /api/wallet/balances - Get XRPL balances

Detailed Documentation

Section titled “Detailed Documentation”

Per-endpoint reference pages (Vaults, Positions, Transactions, Wallet) are not yet written; the route implementations in server/routes.ts are the source of truth in the meantime.

Error Responses

Section titled “Error Responses”

All endpoints return standard error responses:

{
  "error": "Error message describing what went wrong"
}

Common HTTP status codes:

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 404 - Not Found
  • 500 - Internal Server Error

Wallet-Scoped Security Errors

Section titled “Wallet-Scoped Security Errors”

Transaction endpoints require the walletAddress parameter. Missing this parameter returns a 400 error:

Request:

GET /api/transactions

Response (400):

{
  "error": "walletAddress parameter is required"
}

Correct Request:

GET /api/transactions?walletAddress=rN7n7otQDd6FczFgLdlqtyMVUE1FiFzN9K

Rate Limiting

Section titled “Rate Limiting”

Currently no rate limiting in development. Production deployment includes:

  • 100 requests per minute per IP
  • 1000 requests per hour per IP

Network Support

Section titled “Network Support”

All endpoints support network parameter:

  • mainnet - Production XRPL mainnet
  • testnet - XRPL testnet for development

Pass as query parameter: ?network=testnet