API Overview

Introduction

Zafira provides a comprehensive RESTful API for managing cryptocurrency wallets, transactions, charges, webhooks, and tokens across multiple blockchain networks. The API is built with Laravel and uses Laravel Sanctum for authentication.

Base URL

https://zafira-app.vratts.com/api

Authentication

All API endpoints require authentication using Laravel Sanctum. Include the Bearer token in the Authorization header:

Authorization: Bearer {your-token}

Getting an Authentication Token

curl -X POST https://zafira-app.vratts.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

Response Format

All API responses follow a consistent format:

Success Response

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

Error Response

{
  "status": "error",
  "message": "Error description",
  "data": null
}

HTTP Status Codes

• 200 - Success
• 400 - Bad Request (validation errors)
• 401 - Unauthorized (invalid token)
• 404 - Not Found (resource not found)
• 422 - Unprocessable Entity (validation failed)
• 500 - Internal Server Error

Rate Limiting

API endpoints are protected by Laravel's rate limiting middleware. Default limits apply per authenticated user to prevent abuse.

API Endpoints Overview

Wallet Management

• GET /api/wallet/{wallet} - Get wallet details
• GET /api/wallet/{wallet}/balance - Get wallet balance
• GET /api/wallet/{wallet}/tokens - Get wallet tokens

Token Management

• GET /api/wallet/{wallet}/token/{token} - Get specific token details

Charge Management

• POST /api/wallet/{wallet}/charge/create - Create payment charge
• GET /api/wallet/{wallet}/charge/show/{charge} - Get charge details

Transaction Management

• GET /api/wallet/{wallet}/transaction - Get wallet transactions
• POST /api/wallet/{wallet}/transaction/create - Create transaction
• GET /api/wallet/{wallet}/transaction/show/{transaction} - Get transaction details

Webhook Management

• GET /api/wallet/{wallet}/webhook - Get webhook details
• GET /api/wallet/{wallet}/webhook/types - Get webhook types
• GET /api/wallet/{wallet}/webhook/event/{event} - Get webhook event details
• POST /api/wallet/{wallet}/webhook/create - Create webhook
• GET /api/wallet/{wallet}/webhook/delete/{webhook} - Delete webhook

System Management

• GET /api/supervisor - System supervisor endpoint

Data Models

Wallet Model

• Fields: id, name, address, description, is_mainnet, created_at, updated_at
• Hidden: private_key, mnemonic, user_id, network_id (for security)
• Relationships:
  • user() - Belongs to User
  • network() - Belongs to Network
  • walletTokens() - Has many WalletToken
  • transactions() - Has many WalletTransactions
  • charges() - Has many Charge
  • webhooks() - Has many Webhooks

WalletToken Model

• Fields: id, contract, name, symbol, decimals, is_native, is_active, is_testnet
• Hidden: wallet_id
• Special: contract defaults to 0x0000000000000000000000000000000000000000 for native tokens

WalletBalance Model

• Fields: amount, last_balance
• Hidden: id, wallet_id, token_id
• Casts: amount and last_balance as decimal with 18 decimal places

Charge Model

• Fields: id, wallet_id, sub_wallet_id, token_id, amount, status, mode, expires, content, info, uuid
• Casts: amount as decimal with 18 decimal places, expires as integer
• Status Logic: Automatically calculates status based on expiration time

WalletTransactions Model

• Fields: id, amount, type, status, tx_hash, block_number, block_timestamp, block_hash, nonce, gas, gas_price, gas_used, cumulative_gas_used, receipt_status
• Hidden: wallet_id, token_id, input, info
• Casts: All amount fields as decimal with 18 decimal places

Webhooks Model

• Fields: id, url, type, status, events, headers
• Hidden: signature, wallet_id
• Casts: events and headers as arrays
• Encryption: signature and headers are encrypted

Security Features

• All sensitive data (private keys, mnemonics, signatures) is encrypted using Laravel's encryption
• API tokens are managed through Laravel Sanctum
• Wallet access is validated through middleware
• All requests require proper authentication
• Sensitive fields are hidden from API responses

Next Steps

• Wallet Management - Detailed wallet API documentation
• Token Management - Token-related endpoints
• Transaction Management - Transaction endpoints
• Webhook Management - Webhook configuration
• Examples - Practical API usage examples