Vezgo Python SDK

Official Python SDK for the Vezgo Cryptocurrency API.

What is Vezgo?

Vezgo is a unified cryptocurrency API that allows you to connect with cryptocurrency exchanges, wallets, and blockchain protocols. Instead of manually integrating with multiple exchange APIs like Coinbase, Binance, or blockchain APIs - you can simply use Vezgo for them all.

Features

• 🔐 Secure Authentication - JWT-based token authentication
• 📊 Account Data - Retrieve balances, positions, and wallet information
• 💸 Transaction History - Full transaction history across all connected accounts
• 📈 Balance History - Historical balance tracking over time
• 📋 Order History - Trading order history from exchanges
• 🏢 40+ Exchanges - Support for major cryptocurrency exchanges
• ⛓️ 20+ Blockchains - Direct blockchain integrations
• 👛 250+ Wallets - Wallet connection support

Installation

pip install vezgo

Configuration

Copy the example environment file and add your credentials:

cp env.example .env

Edit .env with your Vezgo API credentials from the Vezgo Dashboard:

VEZGO_CLIENT_ID=your_client_id_here
VEZGO_CLIENT_SECRET=your_client_secret_here

Quick Start

from vezgo import Vezgo

# Initialize the client with your API credentials
vezgo = Vezgo(
    client_id="your_client_id",
    secret="your_secret"
)

# Get list of supported providers (no user login required)
providers = vezgo.providers.get_list()
print(f"Vezgo supports {len(providers)} providers")

# Get team information
team = vezgo.get_team()
print(f"Team: {team['name']}")

User Authentication

To access user-specific data like accounts and transactions, you need to login as a user:

from vezgo import Vezgo

vezgo = Vezgo(
    client_id="your_client_id",
    secret="your_secret"
)

# Login as a specific user (use your internal user ID)
user = vezgo.login("user_123")

# Now you can access user-specific resources
accounts = user.accounts.get_list()
for account in accounts:
    print(f"Account: {account['provider']['display_name']}")
    for balance in account.get('balances', []):
        print(f"  {balance['ticker']}: {balance['amount']}")

API Reference

Provider APIs

These APIs don't require user authentication:

Get All Providers

providers = vezgo.providers.get_list()

# Each provider includes:
# - name: unique identifier
# - display_name: human-friendly name
# - auth_type: oauth, password, token, or wallet
# - credentials: required credential types
# - features: supported features (positions, transactions, nfts, etc.)

Get a Specific Provider

coinbase = vezgo.providers.get_one("coinbase")
print(f"Auth type: {coinbase['auth_type']}")
print(f"Credentials: {coinbase['credentials']}")

Account APIs

These APIs require user authentication:

List All Accounts

user = vezgo.login("user_123")
accounts = user.accounts.get_list()

for account in accounts:
    print(f"ID: {account['id']}")
    print(f"Provider: {account['provider']['display_name']}")
    print(f"Status: {account['status']}")
    print(f"Total Value: ${account.get('fiat_value', '0')}")

Get a Specific Account

account = user.accounts.get_one("603522490d2b02001233a5d6")

Add an Account (Direct API - Enterprise Only)

Add accounts directly via API without the Connect widget. This is useful for wallet addresses and API key integrations.

Note: This endpoint requires Enterprise access. Contact Vezgo for more information.

# Add a Bitcoin wallet by address
account = user.accounts.add(
    provider="bitcoin",
    credentials={"address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"},
    name="My Bitcoin Wallet"
)
print(f"Account created: {account['id']}")

# Add an Ethereum wallet
account = user.accounts.add(
    provider="ethereum",
    credentials={"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f..."},
    name="My ETH Wallet",
    sync_transactions=True,
    sync_nfts=True
)

# Add an exchange with API keys
account = user.accounts.add(
    provider="binance",
    credentials={
        "apiKey": "your_api_key",
        "apiSecret": "your_api_secret"
    },
    sync_transactions=True,
    daily_sync=True
)

Parameters:

• provider (required): Provider name (e.g., "bitcoin", "ethereum", "binance")
• credentials (required): Provider-specific credentials
• name: Optional account name
• sync_transactions: Whether to sync transactions (default: True)
• sync_nfts: Whether to sync NFTs
• daily_sync: Whether to enable daily automatic sync

Sync an Account

Trigger a refresh to fetch the latest data from the provider:

account = user.accounts.sync("603522490d2b02001233a5d6")
print(f"Sync status: {account['status']}")

Remove an Account

user.accounts.remove("603522490d2b02001233a5d6")

Transaction APIs

List Transactions

user = vezgo.login("user_123")

# Get all transactions for an account
transactions = user.transactions.get_list(
    account_id="603522490d2b02001233a5d6"
)

# With filters
transactions = user.transactions.get_list(
    account_id="603522490d2b02001233a5d6",
    ticker="BTC",                    # Filter by asset
    from_date="2024-01-01",          # Start date
    to_date="2024-06-30",            # End date
    types="trade,deposit",           # Filter by type
    sort="desc",                     # Sort order
    limit=100                        # Max results
)

for tx in transactions:
    print(f"Type: {tx['transaction_type']}")
    for part in tx.get('parts', []):
        print(f"  {part['direction']}: {part['amount']} {part['ticker']}")

Get a Specific Transaction

tx = user.transactions.get_one(
    account_id="603522490d2b02001233a5d6",
    tx_id="603522490d2b02001233a5d7"
)

Balance History APIs

Get Balance History

user = vezgo.login("user_123")

history = user.history.get_list(
    account_id="603522490d2b02001233a5d6",
    from_date="2024-01-01",
    to_date="2024-06-30"
)

for entry in history:
    print(f"Date: {entry['date']}, Value: ${entry['fiat_value']}")

Order APIs

List Orders

user = vezgo.login("user_123")

orders = user.orders.get_list(
    account_id="651538b55e8e333d9c7cdc0d",
    from_date="2024-01-01",
    sort="desc"
)

for order in orders:
    print(f"Order: {order['side']} {order['base_ticker']}/{order['quote_ticker']}")
    print(f"Status: {order['order_status']}")
    print(f"Filled: {order['filled_quantity']} @ {order['average_execution_price']}")

Get a Specific Order

order = user.orders.get_one(
    account_id="603522490d2b02001233a5d6",
    order_id="651538b55e8e333d9c7cdc0d"
)

Error Handling

The SDK provides specific exception classes for different error types:

from vezgo import (
    Vezgo,
    VezgoError,
    VezgoAuthenticationError,
    VezgoAPIError,
    VezgoValidationError,
    VezgoNotFoundError,
    VezgoRateLimitError,
)

try:
    user = vezgo.login("user_123")
    account = user.accounts.get_one("invalid_id")
except VezgoNotFoundError as e:
    print(f"Account not found: {e.message}")
except VezgoAuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except VezgoRateLimitError as e:
    print(f"Rate limit exceeded: {e.message}")
except VezgoAPIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
except VezgoError as e:
    print(f"Vezgo error: {e.message}")

Context Manager Support

The SDK supports context managers for automatic cleanup:

with Vezgo(client_id="...", secret="...") as vezgo:
    providers = vezgo.providers.get_list()
    # Connection is automatically closed when exiting the block

Configuration Options

vezgo = Vezgo(
    client_id="your_client_id",       # Required
    secret="your_secret",             # Required
    base_url="https://api.vezgo.com/v1",  # Optional, default API URL
    connect_url="https://connect.vezgo.com",  # Optional, Connect widget URL
    timeout=30.0,                     # Optional, request timeout in seconds
)

Connecting Users (Frontend Integration)

To connect user accounts, you'll need to use Vezgo Connect in your frontend. Here's how the flow works:

1. Backend: Generate a user token

user = vezgo.login("user_123")
token = user.get_token()
# Send this token to your frontend

2. Frontend: Use the token with Vezgo Connect (JavaScript)

// Use the vezgo-sdk-js package or redirect to Connect URL
const { url, token } = await getConnectDataFromYourBackend();

// Redirect to Vezgo Connect or use the SDK widget
window.location.href = `${url}&token=${token}`;

3. Backend: Handle the callback to receive the connected account

For full frontend integration, see the JavaScript SDK.

Documentation

• Vezgo API Documentation
• API Specification
• JavaScript SDK

Support

• Email: hello@vezgo.com
• Documentation: https://vezgo.com/docs

License

MIT License - see LICENSE for details.