Skip to content

Latest commit

 

History

History
442 lines (333 loc) · 7.11 KB

api-reference.md

File metadata and controls

442 lines (333 loc) · 7.11 KB

API Reference

Base URL

http://localhost:8080

REST API Endpoints

Health Check

GET /health

Health check endpoint.

Response:

200 OK
"OK"

Initialize Vault

POST /vault/initialize

Creates a new vault for a user.

Request Body:

{
  "user_pubkey": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}

Response:

{
  "signature": "5J8...xyz",
  "status": "success"
}

Status Codes:

  • 200: Success
  • 400: Invalid request
  • 500: Internal server error

Deposit Collateral

POST /vault/deposit

Deposits USDT collateral into user's vault.

Request Body:

{
  "user_pubkey": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
  "amount": 1000000000
}

Response:

{
  "signature": "5J8...xyz",
  "status": "success"
}

Notes:

  • Amount is in smallest unit (6 decimals for USDT)
  • Example: 1000000000 = 1000 USDT

Withdraw Collateral

POST /vault/withdraw

Withdraws USDT collateral from user's vault.

Request Body:

{
  "user_pubkey": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
  "amount": 500000000
}

Response:

{
  "signature": "5J8...xyz",
  "status": "success"
}

Error Responses:

{
  "error": "Insufficient available balance"
}

Get Vault Balance

GET /vault/balance/:user

Retrieves vault balance for a user.

Parameters:

  • user (path): User's public key

Example Request:

GET /vault/balance/HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH

Response:

{
  "vault_pubkey": "8Kag...def",
  "total_balance": 1000000000,
  "locked_balance": 300000000,
  "available_balance": 700000000
}

Get Transaction History

GET /vault/transactions/:user

Retrieves transaction history for a user's vault.

Parameters:

  • user (path): User's public key

Example Request:

GET /vault/transactions/HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH

Response:

[
  {
    "id": 1,
    "vault_pubkey": "8Kag...def",
    "tx_type": "deposit",
    "amount": 1000000000,
    "signature": "5J8...xyz",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  {
    "id": 2,
    "vault_pubkey": "8Kag...def",
    "tx_type": "lock",
    "amount": 300000000,
    "signature": "4K7...abc",
    "timestamp": "2024-01-15T11:00:00Z"
  }
]

Transaction Types:

  • deposit: Collateral deposited
  • withdrawal: Collateral withdrawn
  • lock: Collateral locked for position
  • unlock: Collateral unlocked
  • transfer_in: Collateral received from transfer
  • transfer_out: Collateral sent via transfer

Get Total Value Locked (TVL)

GET /vault/tvl

Returns the total value locked across all vaults.

Response:

{
  "tvl": 50000000000000,
  "timestamp": "2024-01-15T12:00:00Z"
}

Get System Statistics

GET /vault/stats

Returns comprehensive system statistics.

Response:

{
  "total_vaults": 1523,
  "tvl": 50000000000000,
  "total_locked": 15000000000000,
  "total_available": 35000000000000,
  "avg_balance": 32834223,
  "utilization_rate": 30.0
}

Fields:

  • total_vaults: Number of vaults
  • tvl: Total value locked
  • total_locked: Total locked collateral
  • total_available: Total available collateral
  • avg_balance: Average balance per vault
  • utilization_rate: Percentage of collateral locked

WebSocket API

Connection

const ws = new WebSocket('ws://localhost:8081/ws');

Message Types

Balance Update

Sent when vault balance changes.

{
  "type": "balance_update",
  "vault_pubkey": "8Kag...def",
  "total_balance": 1000000000,
  "locked_balance": 300000000,
  "available_balance": 700000000
}

Deposit Notification

{
  "type": "deposit",
  "vault_pubkey": "8Kag...def",
  "amount": 1000000000,
  "signature": "5J8...xyz"
}

Withdrawal Notification

{
  "type": "withdrawal",
  "vault_pubkey": "8Kag...def",
  "amount": 500000000,
  "signature": "4K7...abc"
}

Lock/Unlock Notifications

{
  "type": "lock",
  "vault_pubkey": "8Kag...def",
  "amount": 300000000
}

TVL Update

Periodic TVL updates (every 10 seconds).

{
  "type": "tvl_update",
  "tvl": 50000000000000
}

Error Message

{
  "type": "error",
  "message": "Connection error"
}

Client Example

const ws = new WebSocket('ws://localhost:8081/ws');

ws.onopen = () => {
  console.log('Connected to vault updates');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  switch(message.type) {
    case 'balance_update':
      console.log('Balance updated:', message);
      break;
    case 'deposit':
      console.log('Deposit:', message);
      break;
    case 'tvl_update':
      console.log('TVL:', message.tvl);
      break;
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected');
};

Error Responses

All error responses follow this format:

{
  "error": "Error description"
}

Common Error Messages:

  • "Invalid user pubkey: <details>": Malformed public key
  • "Invalid mint: <details>": Malformed mint address
  • "Insufficient available balance": Not enough balance for withdrawal
  • "Internal server error": Backend error

Rate Limiting

  • REST API: 100 requests per minute per IP
  • WebSocket: 10 connections per IP

Authentication

Currently no authentication required for development. Production deployment should implement:

  • API key authentication
  • JWT tokens
  • Request signing

Code Examples

JavaScript/TypeScript

import axios from 'axios';

const API_BASE = 'http://localhost:8080';

// Initialize vault
async function initializeVault(userPubkey: string, mint: string) {
  const response = await axios.post(`${API_BASE}/vault/initialize`, {
    user_pubkey: userPubkey,
    mint: mint
  });
  return response.data;
}

// Deposit
async function deposit(userPubkey: string, amount: number) {
  const response = await axios.post(`${API_BASE}/vault/deposit`, {
    user_pubkey: userPubkey,
    amount: amount
  });
  return response.data;
}

// Get balance
async function getBalance(userPubkey: string) {
  const response = await axios.get(`${API_BASE}/vault/balance/${userPubkey}`);
  return response.data;
}

Python

import requests

API_BASE = 'http://localhost:8080'

def get_balance(user_pubkey):
    response = requests.get(f'{API_BASE}/vault/balance/{user_pubkey}')
    return response.json()

def deposit(user_pubkey, amount):
    response = requests.post(
        f'{API_BASE}/vault/deposit',
        json={'user_pubkey': user_pubkey, 'amount': amount}
    )
    return response.json()

cURL

# Get balance
curl http://localhost:8080/vault/balance/HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH

# Deposit
curl -X POST http://localhost:8080/vault/deposit \
  -H "Content-Type: application/json" \
  -d '{"user_pubkey":"HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH","amount":1000000000}'

# Get TVL
curl http://localhost:8080/vault/tvl