> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sonarx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Filter Transactions
> Filter transactions by various criteria
**Range Filter Constraint**: Use either block range (`from_block`/`to_block`) OR datetime range (`from_datetime`/`to_datetime`), but not both simultaneously. These filter pairs are mutually exclusive.
**Block Range Limit**: Block range queries cannot exceed 100 blocks.
## OpenAPI
````yaml POST /api/v1/customer/{chain}/transactions/filter
openapi: 3.1.0
info:
title: SonarX EVM API - Transactions
description: >-
Query transaction data, receipts, and fee history for EVM-compatible
networks.
version: 1.0.0
servers:
- url: https://api-gateway.sonarx.com
description: Production API
security:
- apiKey: []
tags:
- name: Transactions
description: Query transaction data, receipts, and fee history
paths:
/api/v1/customer/{chain}/transactions/filter:
post:
tags:
- Transactions
summary: Filter Transactions
description: >-
Filter transactions by various criteria. Use either block range
(`from_block`/`to_block`) OR datetime range
(`from_datetime`/`to_datetime`), not both. Block range cannot exceed 100
blocks.
operationId: filterTransactions
parameters:
- $ref: '#/components/parameters/ChainPath'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionFilterRequest'
examples:
byBlockRange:
summary: Filter by block range
value:
from_block: 81901160
to_block: 81901165
byFromAddress:
summary: Filter by sender address
value:
from_block: 81901160
to_block: 81901165
from_address:
- '0xef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c'
byToAddress:
summary: Filter by recipient address
value:
from_block: 81901160
to_block: 81901165
to_address:
- '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
responses:
'200':
description: Filtered transactions
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionFilterResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
ChainPath:
name: chain
in: path
description: The blockchain network to query
required: true
schema:
type: string
enum:
- polygon
example: polygon
Limit:
name: limit
in: query
description: Maximum number of results (1-50)
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 10
Offset:
name: offset
in: query
description: Number of results to skip for pagination
required: false
schema:
type: integer
minimum: 0
default: 0
schemas:
TransactionFilterRequest:
allOf:
- $ref: '#/components/schemas/RangeFilterRequest'
- type: object
properties:
from_address:
oneOf:
- type: string
- type: array
items:
type: string
maxItems: 10
description: Sender address(es) to filter by (max 10)
to_address:
oneOf:
- type: string
- type: array
items:
type: string
maxItems: 10
description: Recipient address(es) to filter by (max 10)
address:
oneOf:
- type: string
- type: array
items:
type: string
maxItems: 10
description: Address(es) as sender or recipient (max 10)
TransactionFilterResponse:
type: object
properties:
offset:
type: integer
limit:
type: integer
result:
type: array
items:
$ref: '#/components/schemas/Transaction'
count:
type: integer
example:
offset: 0
limit: 10
result:
- block_number: 81901160
timestamp: 1768922292
datetime: '2026-01-20T15:18:12'
transaction_hash: '0x00dcc066aad65ae4f10c0fc4ec1fac5d3693c12c01d98a9f6a87448be9b26200'
transaction_index: 66
version: 0
from_address: '0xef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c'
to_address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
value: 0
usd_value: 0
price: 0.132488
transaction_fee: 0.02846459476200589
usd_transaction_fee: 0.0037712172308286365
gas_price_gwei: 631.718297388
effective_gas_price_gwei: 631.718297388
max_fee_per_gas_gwei: 843.150825088
max_priority_fee_per_gas_gwei: 28.049
gas_limit: 90878
gas_used: 45059
gas_used_pct: 0.4958185699509232
cumulative_gas_used: 9299360
transaction_type: 2
contract_address: null
status: true
count: 1
RangeFilterRequest:
type: object
description: >-
Base filter request with range parameters. Validation rules: (1) Must
provide either block range OR datetime range, not both and not neither.
(2) When using block range, both from_block AND to_block are required.
(3) When using datetime range, both from_datetime AND to_datetime are
required. (4) to_block must be >= from_block. (5) to_datetime must be >=
from_datetime. (6) Block range cannot exceed 100 blocks.
properties:
from_block:
type: integer
minimum: 0
description: Start block number. Required if using block range.
to_block:
type: integer
minimum: 0
description: >-
End block number. Required if using block range. Must be >=
from_block and within 100 blocks.
from_datetime:
type: string
format: date-time
description: >-
Start datetime (ISO 8601, timezone required, e.g.,
2024-01-15T10:30:00Z or 2024-01-15T10:30:00+00:00). Required if
using datetime range.
to_datetime:
type: string
format: date-time
description: >-
End datetime (ISO 8601, timezone required, e.g.,
2024-01-15T10:30:00Z or 2024-01-15T10:30:00+00:00). Required if
using datetime range. Must be >= from_datetime.
Transaction:
type: object
properties:
block_number:
type: integer
description: Block number containing this transaction
timestamp:
type: integer
description: Unix timestamp of the block
datetime:
type: string
format: date-time
description: ISO 8601 formatted datetime
transaction_hash:
type: string
description: Hash of the transaction
transaction_index:
type: integer
description: Position of the transaction in the block
version:
type: integer
description: Transaction version
from_address:
type: string
description: Sender address
to_address:
type: string
nullable: true
description: Recipient address
value:
type: number
description: Value transferred in native token
usd_value:
type: number
description: USD value of the transfer
price:
type: number
description: Native token price in USD
transaction_fee:
type: number
description: Transaction fee in native token
usd_transaction_fee:
type: number
description: Transaction fee in USD
gas_price:
type: number
description: Gas price in native token
gas_price_gwei:
type: number
description: Gas price in Gwei
effective_gas_price:
type: number
description: Effective gas price
effective_gas_price_gwei:
type: number
description: Effective gas price in Gwei
max_fee_per_gas:
type: number
nullable: true
description: Maximum fee per gas (EIP-1559)
max_fee_per_gas_gwei:
type: number
nullable: true
max_priority_fee_per_gas:
type: number
nullable: true
description: Maximum priority fee (EIP-1559)
max_priority_fee_per_gas_gwei:
type: number
nullable: true
gas_limit:
type: integer
description: Maximum gas allowed
gas_used:
type: integer
description: Actual gas used
gas_used_pct:
type: number
description: Percentage of gas limit used
cumulative_gas_used:
type: integer
description: Total gas used up to this transaction
input:
type: string
description: Transaction input data
transaction_type:
type: integer
description: Transaction type (0=legacy, 1=access list, 2=EIP-1559)
contract_address:
type: string
nullable: true
description: Contract address created
status:
type: boolean
description: Transaction success status
source_value:
type: string
description: Raw value in wei
source_gas_price:
type: string
source_effective_gas_price:
type: string
source_max_fee_per_gas:
type: string
nullable: true
source_max_priority_fee_per_gas:
type: string
nullable: true
example:
block_number: 81911103
timestamp: 1768942178
datetime: '2026-01-20T20:49:38'
transaction_hash: '0x0063079708b5fab44762765a01c17ab2754ebc15cb9ecd0e14fcbbd520452c27'
transaction_index: 80
version: 0
from_address: '0xb63c1246a11edc1e784c39ab95295e4180c5071b'
to_address: '0x9ead30c8518a19f0b493eea1bd5af8fcc5fd4ba2'
value: 1.e-7
usd_value: 1.30889e-8
price: 0.130889
transaction_fee: 0.000762618316404
usd_transaction_fee: 0.00009981834881580316
gas_price: 3.6315157924e-8
gas_price_gwei: 36.315157924
effective_gas_price: 3.6315157924e-8
effective_gas_price_gwei: 36.315157924
max_fee_per_gas: null
max_fee_per_gas_gwei: null
max_priority_fee_per_gas: null
max_priority_fee_per_gas_gwei: null
gas_limit: 21200
gas_used: 21000
gas_used_pct: 0.9905660377358491
cumulative_gas_used: 9824334
input: 0x
transaction_type: 0
contract_address: null
status: true
source_value: '100000000000'
source_gas_price: '36315157924'
source_effective_gas_price: '36315157924'
source_max_fee_per_gas: null
source_max_priority_fee_per_gas: null
ErrorResponse:
type: object
properties:
detail:
type: string
required:
- detail
responses:
BadRequest:
description: Bad Request - Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingBlockNumber:
summary: Missing block number
value:
detail: block_number is required
mixedRangeParams:
summary: Mixed block and datetime parameters
value:
detail: >-
Cannot mix block and datetime parameters. Use either
from_block/to_block or from_datetime/to_datetime, not both
missingRangeParams:
summary: No range parameters provided
value:
detail: >-
Either block range (from_block/to_block) or datetime range
(from_datetime/to_datetime) must be provided
incompleteBlockRange:
summary: Incomplete block range
value:
detail: Both from_block and to_block must be provided together
blockRangeTooLarge:
summary: Block range exceeds limit
value:
detail: Block range cannot exceed 100 blocks
Unauthorized:
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
detail: Invalid API key
InternalError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
detail: An unexpected error occurred
securitySchemes:
apiKey:
type: apiKey
in: header
name: apikey
description: API key for authentication
````