transactions

API Context — Endpoint: https://api.onesource.io/federation/{'{'}chain{'}'}/graphql | Auth Header: x-bp-token: BP-{YOUR_API_KEY} | Method: POST | Content-Type: application/json

Search and filter transactions with pagination.

Schema Definition

transactions(
  first: Int = 10
  after: Cursor
  where: TransactionFilter
  orderBy: TransactionOrderBy
  orderDirection: OrderDirection
): TransactionList!

Arguments

Argument	Type	Description
`first`	`Int` scalar	Maximum number of results to return (default: `10`, max: `100`).
`after`	`Cursor` scalar	`Cursor` for pagination. Pass the `endCursor` from a previous query to get the next page.
`where`	`TransactionFilter` input	Filter criteria for transactions.
`orderBy`	`TransactionOrderBy` enum	Field to sort results by.
`orderDirection`	`OrderDirection` enum	Sort direction (ascending or descending).

Return Type

Type	Description
`TransactionList!` object	Paginated list of transactions with optional aggregate statistics.

Common Use Cases

Display a user's complete transaction history by filtering on the from or to address fields in TransactionFilter.
Find all transactions involving a specific address (as sender or recipient) using the involvesAddress filter.
Monitor large value transfers by filtering with value: { gte: "1000000000000000000" } (1 ETH in wei).
Track interactions with specific smart contracts by filtering on the to address.
Analyze gas price trends by filtering with gasPrice: { gte, lte } ranges and ordering with orderBy: GAS.
Query transactions within a block range using blockNumber: { gte, lte } or a time window using timestamp: { gte, lte }.
Filter by transaction outcome using status: SUCCESS, status: FAILED, or status: PENDING.
Find contract deployment transactions using hasContractCreation: true.

Example

Query

Get 5 Most Recent Transactions to the USDT Contract

query GetRecentUSDTTransactions(
  $where: TransactionFilter
  $first: Int
  $orderBy: TransactionOrderBy
  $orderDirection: OrderDirection
) {
  transactions(
    where: $where
    first: $first
    orderBy: $orderBy
    orderDirection: $orderDirection
  ) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      hash
      timestamp
      from {
        address
      }
      to {
        address
      }
      value {
        raw
        formatted
      }
      gas {
        limit
        price
        used
      }
      block {
        number
      }
      status
    }
  }
}

Variables

{
  "where": {
    "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
  },
  "first": 5,
  "orderBy": "TIMESTAMP",
  "orderDirection": "DESC"
}

Response

{
  "data": {
    "transactions": {
      "totalCount": 483920,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6NX0="
      },
      "entries": [
        {
          "hash": "0x59fb9291481bc4e944928f468ffe6977396bd96cdfb0c28a1438121953c0bfdd",
          "timestamp": "2025-10-17T08:04:11Z",
          "from": {
            "address": "0x80787af194c33b74a811f5e5c549316269d7ee1a"
          },
          "to": {
            "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
          },
          "value": {
            "raw": "0",
            "formatted": "0.0"
          },
          "gas": {
            "limit": 110000,
            "price": "3000000000",
            "used": 63209
          },
          "block": {
            "number": 23598257
          },
          "status": "SUCCESS"
        },
        {
          "hash": "0x7b794f64afb33ed5bf5a6856d3407fd03f89a34b1a0bf27dfc193490e14717b0",
          "timestamp": "2025-10-17T08:04:11Z",
          "from": {
            "address": "0xe0ca2012c3304e41c9d6e6a0d7f62c33b74356cf"
          },
          "to": {
            "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
          },
          "value": {
            "raw": "0",
            "formatted": "0.0"
          },
          "gas": {
            "limit": 49273,
            "price": "1297332589",
            "used": 46321
          },
          "block": {
            "number": 23598257
          },
          "status": "SUCCESS"
        },
        {
          "hash": "0x4eada9f9ff04b915ca6273a4ad92635a8fcd592ed7c0807aab7483506d9f906d",
          "timestamp": "2025-10-17T08:04:11Z",
          "from": {
            "address": "0x2df9b935c44057ac240634c7536511d8aa03028d"
          },
          "to": {
            "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
          },
          "value": {
            "raw": "0",
            "formatted": "0.0"
          },
          "gas": {
            "limit": 84000,
            "price": "1608773990",
            "used": 63197
          },
          "block": {
            "number": 23598257
          },
          "status": "SUCCESS"
        },
        {
          "hash": "0xd50760ac010e21f902bca8e961a0de92d3df594205a52443093e6a3651312a4d",
          "timestamp": "2025-10-17T08:04:11Z",
          "from": {
            "address": "0x8e04af7f7c76daa9ab429b1340e0327b5b835748"
          },
          "to": {
            "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
          },
          "value": {
            "raw": "0",
            "formatted": "0.0"
          },
          "gas": {
            "limit": 250000,
            "price": "1323416235",
            "used": 63197
          },
          "block": {
            "number": 23598257
          },
          "status": "SUCCESS"
        },
        {
          "hash": "0xf3ab3a5b91b1365388ef446ecff71f1d95e8a48a0816d8572b9759ac5d5e43cd",
          "timestamp": "2025-10-17T08:04:11Z",
          "from": {
            "address": "0x5fa8139192d8bb5f6684c6d808b7665e02df4833"
          },
          "to": {
            "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
          },
          "value": {
            "raw": "0",
            "formatted": "0.0"
          },
          "gas": {
            "limit": 70447,
            "price": "1601480988",
            "used": 63209
          },
          "block": {
            "number": 23598257
          },
          "status": "SUCCESS"
        }
      ]
    }
  }
}

Implementation Notes

note

The transactions query returns a TransactionList containing entries, totalCount, pageInfo, and optional stats for aggregate analytics.
The default first value is 10. OneSource enforces a maximum first value of 100. Adjust based on your needs.
Use cursor-based pagination with after and pageInfo.endCursor to page through results. Check pageInfo.hasNextPage to determine if more pages exist.
The from and to fields return Address objects, not plain strings. Use from { address } or to { address } to access the hex string. You can also traverse into balances and other address fields.
The to field is null for contract creation transactions. Use hasContractCreation: true in the filter to find these, and access the deployed contract via the contractCreated field.
The value field returns a TokenAmount object with raw (wei string), formatted (human-readable), and decimals fields. Use formatted for display rather than converting manually.
Gas information is nested under the gas field as a GasInfo object with limit, price, used, feeCap, and tipCap. For EIP-1559 transactions, feeCap and tipCap are populated; for legacy transactions, use price.
The block field returns a Block object (or null if pending). Access the block number with block { number } and confirmations with the top-level confirmations field.
The timestamp field returns an ISO 8601 formatted string (e.g., "2025-10-17T08:04:11Z"), not a Unix integer.
Range filters use structured input objects with gte and lte fields — e.g., value: { gte: "1000000000000000000" }, blockNumber: { gte: 18000000, lte: 19000000 }, timestamp: { gte: "2025-01-01T00:00:00Z" }.
Use orderBy and orderDirection (ASC or DESC) to ensure consistent ordering when paginating. Available orderBy values are BLOCK_NUMBER, TIMESTAMP, VALUE, HASH, GAS, NONCE, FROM, and TO.
The optional stats field on the response provides aggregate statistics including totalCount, totalValue, averageGasPrice, averageGasUsed, and uniqueAddresses.
To look up a single transaction by hash, use the transaction query instead.

Schema Definition​

Arguments​

Return Type​

Common Use Cases​

Example​

Query​

Get 5 Most Recent Transactions to the USDT Contract​

Variables​

Response​

Implementation Notes​