Skip to main content
GET
/
api
/
v1
/
transactions
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid date format for start_date. Use YYYY-MM-DD.",
    "field": "start_date"
  }
}

​
Authentication

This endpoint requires authentication via Bearer token. 
Authorization: Bearer YOUR_API_KEY

​
Request

​
workspace_id
string
required
The workspace ID to fetch transactions for
​
wallet_id
string
Filter by specific wallet ID
​
chain
string
Filter by blockchain network (ethereum, polygon, arbitrum, bsc)
​
token
string
Filter by token symbol (e.g., USDC, ETH, DAI)
​
direction
string
Filter by transaction direction
  • inflow - Incoming transactions
  • outflow - Outgoing transactions
​
tag_ids
string
Comma-separated tag IDs to filter by
​
start_date
string
Start date for filtering (ISO 8601 format: YYYY-MM-DD)
​
end_date
string
End date for filtering (ISO 8601 format: YYYY-MM-DD)
​
min_amount
number
Minimum transaction amount (in token units)
​
max_amount
number
Maximum transaction amount (in token units)
​
has_tags
boolean
Filter by tagged (true) or untagged (false) transactions
​
has_notes
boolean
Filter transactions with notes
​
sort
string
default:"timestamp_desc"
Sort order
  • timestamp_desc - Newest first (default)
  • timestamp_asc - Oldest first
  • amount_desc - Highest amount first
  • amount_asc - Lowest amount first
​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"50"
Number of transactions per page (max 200)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
​
pagination
object
​
summary
object

​
Example Request

curl -X GET "https://api.cryptotally.xyz/v1/transactions?workspace_id=ws_123&direction=inflow&start_date=2024-01-01&end_date=2024-03-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

{
  "success": true,
  "data": [
    {
      "id": "txn_abc123",
      "tx_hash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
      "wallet_id": "wlt_abc123",
      "wallet_label": "Treasury",
      "chain": "ethereum",
      "from_address": "0x1234567890abcdef1234567890abcdef12345678",
      "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "token": {
        "symbol": "USDC",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "decimals": 6
      },
      "amount": "5000.00",
      "fiat_value": 5000.00,
      "direction": "inflow",
      "type": "transfer",
      "timestamp": "2024-03-15T14:32:00Z",
      "tags": [
        {
          "id": "tag_xyz789",
          "name": "Customer Payment",
          "color": "#10B981"
        }
      ],
      "notes": "Payment from Client ABC for Q1 2024 services - Invoice #12345",
      "attachments": [
        {
          "id": "att_def456",
          "file_name": "invoice-12345.pdf",
          "file_url": "https://storage.cryptotally.xyz/attachments/invoice-12345.pdf",
          "file_size": 245678,
          "uploaded_at": "2024-03-15T15:00:00Z"
        }
      ],
      "explorer_url": "https://etherscan.io/tx/0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
  ],
  "pagination": {
    "total": 147,
    "page": 1,
    "pages": 3,
    "limit": 50
  },
  "summary": {
    "total_inflow": 125000.00,
    "total_outflow": 0,
    "net_flow": 125000.00,
    "transaction_count": 147
  }
}

​
Filtering Examples

​
Get all customer payments in Q1 2024

GET /api/v1/transactions?workspace_id=ws_123&tag_ids=tag_payment&start_date=2024-01-01&end_date=2024-03-31&direction=inflow

​
Find large USDC transactions

GET /api/v1/transactions?workspace_id=ws_123&token=USDC&min_amount=10000&sort=amount_desc

​
Get untagged transactions

GET /api/v1/transactions?workspace_id=ws_123&has_tags=false

​
Get all expenses from Operations wallet

GET /api/v1/transactions?workspace_id=ws_123&wallet_id=wlt_ops123&direction=outflow

​
Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid date format for start_date. Use YYYY-MM-DD.",
    "field": "start_date"
  }
}

​
Rate Limits

  • Free Tier: 100 requests per hour
  • Pro Tier: 1,000 requests per hour
  • Enterprise Tier: Custom limits

​
Performance Tips

For large datasets, use date range filters and pagination instead of fetching all transactions at once.
The summary object provides aggregated statistics without needing to process all transactions client-side.
Use wallet_id filter when possible - it’s more efficient than filtering by chain or other parameters.

​
Webhook Support

Subscribe to transaction events:
  • transaction.created - New transaction synced
  • transaction.tagged - Transaction tagged
  • transaction.updated - Notes or attachments added
See Webhooks for setup instructions.

Get Wallets

Fetch wallet list

Create Tag

Create transaction tags

Export Data

Generate CSV exports

Update Transaction

Add tags and notes