Wallet API Reference

Complete API documentation for the Toto Wallet system.

Overview

The Toto Wallet API provides comprehensive functionality for managing Stellar-based wallets, processing transactions, and handling donations.

Base URL

Production: https://api.toto.com/v1/wallet
Testnet: https://api-testnet.toto.com/v1/wallet

Authentication

All API requests require authentication using Firebase Auth tokens:

Authorization: Bearer <firebase_id_token>

Endpoints

Wallet Management

Create Wallet

POST /wallets

Request Body:

{
  "network": "testnet", // or "public"
  "metadata": {
    "name": "User Wallet",
    "description": "Personal donation wallet"
  }
}

Response:

{
  "id": "wallet_123",
  "publicKey": "GABC123...",
  "network": "testnet",
  "createdAt": "2025-01-30T10:00:00Z",
  "status": "active"
}

Get Wallet

GET /wallets/{walletId}

Response:

{
  "id": "wallet_123",
  "publicKey": "GABC123...",
  "network": "testnet",
  "balance": {
    "XLM": "100.0000000",
    "USDC": "50.0000000"
  },
  "createdAt": "2025-01-30T10:00:00Z",
  "lastActivity": "2025-01-30T15:30:00Z"
}

List Wallets

GET /wallets

Query Parameters:

• network (optional): Filter by network
• status (optional): Filter by status
• limit (optional): Number of results (default: 20)
• offset (optional): Pagination offset

Transactions

Send Transaction

POST /wallets/{walletId}/transactions

Request Body:

{
  "destination": "GDEF456...",
  "amount": "10.0000000",
  "asset": "XLM", // or "USDC"
  "memo": "Donation for pet rescue",
  "memoType": "text"
}

Response:

{
  "id": "txn_789",
  "hash": "abc123...",
  "status": "pending",
  "amount": "10.0000000",
  "asset": "XLM",
  "destination": "GDEF456...",
  "createdAt": "2025-01-30T16:00:00Z"
}

Get Transaction

GET /transactions/{transactionId}

Response:

{
  "id": "txn_789",
  "hash": "abc123...",
  "status": "success",
  "amount": "10.0000000",
  "asset": "XLM",
  "source": "GABC123...",
  "destination": "GDEF456...",
  "memo": "Donation for pet rescue",
  "fee": "0.0000100",
  "createdAt": "2025-01-30T16:00:00Z",
  "confirmedAt": "2025-01-30T16:00:05Z"
}

List Transactions

GET /wallets/{walletId}/transactions

Query Parameters:

• type (optional): "sent" or "received"
• asset (optional): Filter by asset
• status (optional): Filter by status
• limit (optional): Number of results
• offset (optional): Pagination offset

Donations

Create Donation

POST /donations

Request Body:

{
  "walletId": "wallet_123",
  "caseId": "case_456",
  "amount": "25.0000000",
  "asset": "XLM",
  "message": "Hope this helps!",
  "anonymous": false
}

Response:

{
  "id": "donation_789",
  "transactionId": "txn_789",
  "caseId": "case_456",
  "amount": "25.0000000",
  "asset": "XLM",
  "message": "Hope this helps!",
  "anonymous": false,
  "status": "pending",
  "createdAt": "2025-01-30T16:30:00Z"
}

Get Donation

GET /donations/{donationId}

List Donations

GET /donations

Query Parameters:

• caseId (optional): Filter by case
• walletId (optional): Filter by wallet
• status (optional): Filter by status

MoonPay Integration

Create MoonPay URL

POST /wallets/{walletId}/moonpay/url

Request Body:

{
  "amount": "100.00",
  "currency": "USD",
  "walletAddress": "GABC123...",
  "redirectURL": "https://toto.com/success"
}

Response:

{
  "url": "https://buy.moonpay.com/?apiKey=...",
  "expiresAt": "2025-01-30T17:00:00Z"
}

MoonPay Webhook

POST /webhooks/moonpay

Headers:

X-Moonpay-Signature: <signature>

Request Body:

{
  "type": "transaction_updated",
  "data": {
    "id": "moonpay_txn_123",
    "status": "completed",
    "cryptoAmount": "100.0000000",
    "cryptoCurrency": "XLM",
    "walletAddress": "GABC123..."
  }
}

Error Handling

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for transaction",
    "details": {
      "required": "10.0000000",
      "available": "5.0000000"
    }
  }
}

Common Error Codes

Code	Description
INSUFFICIENT_BALANCE	Not enough funds for transaction
INVALID_ADDRESS	Invalid Stellar address
NETWORK_ERROR	Stellar network connection issue
TRANSACTION_FAILED	Transaction failed on network
WALLET_NOT_FOUND	Wallet does not exist
UNAUTHORIZED	Invalid or missing authentication
RATE_LIMITED	Too many requests

Rate Limits

• General API: 100 requests per minute
• Transaction Creation: 10 requests per minute
• MoonPay Integration: 50 requests per minute

SDK Examples

JavaScript/TypeScript

import { TotoWalletAPI } from '@toto/wallet-sdk';

const api = new TotoWalletAPI({
  baseURL: 'https://api.toto.com/v1/wallet',
  authToken: 'firebase_id_token'
});

// Create wallet
const wallet = await api.createWallet({
  network: 'testnet',
  metadata: { name: 'My Wallet' }
});

// Send transaction
const transaction = await api.sendTransaction(wallet.id, {
  destination: 'GDEF456...',
  amount: '10.0000000',
  asset: 'XLM',
  memo: 'Donation'
});

Python

from toto_wallet import TotoWalletAPI

api = TotoWalletAPI(
    base_url='https://api.toto.com/v1/wallet',
    auth_token='firebase_id_token'
)

# Create wallet
wallet = api.create_wallet(
    network='testnet',
    metadata={'name': 'My Wallet'}
)

# Send transaction
transaction = api.send_transaction(
    wallet_id=wallet.id,
    destination='GDEF456...',
    amount='10.0000000',
    asset='XLM',
    memo='Donation'
)

Webhooks

Supported Events

• wallet.created
• wallet.updated
• transaction.created
• transaction.completed
• transaction.failed
• donation.created
• donation.completed

Webhook Format

{
  "event": "transaction.completed",
  "timestamp": "2025-01-30T16:00:05Z",
  "data": {
    "transactionId": "txn_789",
    "walletId": "wallet_123",
    "amount": "10.0000000",
    "asset": "XLM"
  }
}

Testing

Testnet Configuration

For testing, use the testnet endpoints and Stellar testnet:

const api = new TotoWalletAPI({
  baseURL: 'https://api-testnet.toto.com/v1/wallet',
  network: 'testnet'
});

Test Data

• Test XLM: Available from Stellar testnet faucet
• Test USDC: Available from Stellar testnet
• Test Wallets: Automatically created for testing

Support

For API support:

• Documentation: Integration Guide
• GitHub: Issues
• Email: api-support@toto.com