transaction

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

Look up a transaction by its hash. Returns null if the transaction doesn't exist or is still pending.

Schema Definition

transaction(
  hash: TransactionHash!
): Transaction

Arguments

Argument	Type	Description
hash	TransactionHash! non-null scalar	The transaction hash to look up (0x-prefixed, 66 characters).

Return Type

Type	Description
Transaction object	A transaction representing a transfer of value or contract interaction.

Common Use Cases

• Monitor transaction finality and confirmation depth for payment systems, exchanges, and dApps.
• Analyze historical gas costs by inspecting the gas field to optimize future transaction pricing and fee strategies.
• Build transaction explorers, wallet dashboards, or audit trails for addresses.
• Verify and debug smart contract calls, including contract deployments (when to is null and contractCreated is populated).
• Retrieve full block context for a transaction via the nested block field.

Example

Query

Verify Payment Status by Transaction Hash

query VerifyPayment($hash: TransactionHash!) {
  transaction(hash: $hash) {
    hash
    timestamp
    status
    confirmations
    from {
      address
    }
    to {
      address
    }
    value {
      raw
      formatted
      decimals
    }
    gas {
      limit
      price
      used
      feeCap
      tipCap
    }
    block {
      number
      timestamp
    }
  }
}

Variables

{
  "hash": "0x22e64f2a255bbe709a702fbc22412339e7fa876b422493b6b7e03aa5fcd3b49c"
}

Response

{
  "data": {
    "transaction": {
      "hash": "0x22e64f2a255bbe709a702fbc22412339e7fa876b422493b6b7e03aa5fcd3b49c",
      "timestamp": "2025-10-18T10:44:47Z",
      "status": "SUCCESS",
      "confirmations": 40059,
      "from": {
        "address": "0x710312405c896cedcaef82cb9105bee07ecbeab8"
      },
      "to": {
        "address": "0x99866915b444637925058a7a9984ab32e2c0714c"
      },
      "value": {
        "raw": "3976740000000000",
        "formatted": "0.00397674",
        "decimals": 18
      },
      "gas": {
        "limit": 21000,
        "price": "1250655772",
        "used": 21000,
        "feeCap": "1500000000",
        "tipCap": "100000000"
      },
      "block": {
        "number": 23602632,
        "timestamp": "2025-10-18T10:44:47Z"
      }
    }
  }
}

Implementation Notes

note

• The transaction query returns null if the transaction doesn't exist or is still pending. Always handle the null case in your application.
• The hash argument is of type TransactionHash! — a 0x-prefixed, 66-character hex string.
• 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, transaction history, and other address fields.
• The to field is null for contract creation transactions. In that case, use the contractCreated field to access the deployed contract (returned as IContract).
• The value field returns a TokenAmount object with raw (wei string), formatted (human-readable with decimals applied), and decimals fields. Use formatted for display instead of converting manually.
• Gas information is nested under the gas field as a GasInfo object. It includes limit (max gas authorized), price (effective gas price in wei), used (actual gas consumed, or null if pending), feeCap (EIP-1559 max fee per gas), and tipCap (EIP-1559 priority fee). For legacy transactions, feeCap and tipCap will be null.
• The block field returns a Block object containing the block number, timestamp, hash, and other block-level data. It is null for pending transactions.
• The confirmations field is a top-level integer on the Transaction type that updates dynamically as new blocks are mined. Higher values indicate greater finality.
• The timestamp field returns an ISO 8601 formatted string (e.g., "2025-10-18T10:44:47Z"), not a Unix integer.
• The status field returns a TransactionStatus enum: SUCCESS, FAILED, or PENDING.
• To search and filter across multiple transactions, use the transactions query with pagination and filtering support.