Coherent API
Search…
Transactions
Find out the historical activity of an address in a readable way
Our endpoint provides reliable insight on transaction data. Less raw hashes, more legible descriptions concerning actions, categories, and metadata that make it easy to tell what actually happened on chain.
GET https://api.coherent.sh/v1/address/{user_address}/transactions
Query Parameters (all optional):
  • limit = int that represents max number of items to return, default 50, max of 100
  • starting_from = UTC timestamp from which you want to start seeing transactions, either chronologically ahead of or before based on order param below; if left empty, will default to current time in UTC
    • Preferred timestamp format is the following (RFC3339 reference; additionally, some Golang docs for time.UTC() that we use internally for our timestamps):
      ISO 8601 Standard
      RFC3339 = "2006-01-02T15:04:05Z07:00"
      Since we return this as part of our response as endingAt, you can just take this value and plug it into the next to paginate easily through our API response
    • We do support other formats - if you're not intensively/programmatically searching through the data but just want a one-time query, these could be ideal to use!
      Other Layouts
      // make sure these are in UTC!
      RFC3339 = "2006-01-02T15:04:05Z07:00"
      layoutISO = "2006-01-02"
      layoutISOWithTime = "2006-01-02 at 3:04pm"
      layoutUS = "Jan 2, 2006"
      layoutUSWithTime = "Jan 2, 2006 at 3:04pm"
      layoutUSFullMonth = "January 2, 2006"
      layoutUSFullMonthWithTime = "January 2, 2006 at 3:04pm
  • order = string for preference of transaction history ordering, either "ascending" or "descending"; defaults to "descending" where all transactions after the first one are chronologically before
  • blockchains = array of string's, can include any of the supported chains:["ethereum", "optimism", "polygon"] - if left empty, will default to all chains
A sample cURL would look like:
curl -H 'x-api-key: your_api_key' https://api.coherent.sh/v1/address/user_address/transactions?limit=10&starting_from=2022-08-03T12:25:56-06:00&order=asc&blockchains=optimism&blockchains=ethereum
The response you get will resemble something along these lines:
Response
{
"address": "0xad44a6d4b7...",
"transactions": [
{
"timestamp": "2022-07-21T17:32:28Z",
"txHash": "0x8884f3c0a34a5...",
"contractName": "seaport",
"fee": {
"amount": 29000,
"currency": "GWEI"
},
"contractType": "marketplace",
"action": "sell",
"description": "Bought BAYC #2345 from carlcortright.eth",
"blockchain": "ethereum-mainnet",
"assetsSent": [
{
"amount": 75.26,
"asset": {
"address": "0xC02aaA39b22...",
"name": "Native ETH",
"symbol": "ETH",
"image": "cdn.coherent.sh/images/sdfasdgsadf.png",
"price": "$1,700",
"standard": "ERC20"
}
}
],
"assetsReceived": [
{
"amount": 1,
"asset": {
"address": "0xC02aaA39b223FE8...",
"name": "Bored Ape Yacht Club",
"symbol": "BAYC",
"image": "cdn.coherent.sh/images/sdfasdgsadf.png",
"price": "$100,218",
"supply": 1,
"standard": "ERC721"
}
}
],
"metadata": {
"purchaser": "coherentapi.eth",
"marketplace": "zora"
}
},
{
...etc., etc.
}
],
"endingAt": "2022-07-12T12:56:15Z"
}

Filters

Soon to be available for Transactions Endpoint, immediately available for use on Streaming

Filters help developers who want to look for very specific actions on-chain.
It's evidently very difficult to find clean ways to partition a blockchain that is infinitely flexible in functionality, but this will be a starting list of ways to filter - if there's any feedback or actions on-chain that you believe aren't covered, reach out to us! We'd love to hear your input.

Actions

Start with actions when filtering; this gives broad access to any swap across all chains/exchanges, or any buy. Think of these as the first broadest filter, and if you need to get more specific, you can then combine these with contractType below to get more specific.

This is the full selection for action:

Actions
approve
bribe
buy
cancel
claim
create
deposit
donate
execute
mint
receive
sell
send
stake
swap
vest
vote
withdraw

Contract Types

Another layer of specificity, and when filtering think of these as ways to select on an actual smart contract type itself - e.g.
marketplace contracts enable the sell and buy of NFT's, not the nft contract itself.
Hence, please be careful as you're adding this second category. If you're looking for actions that the user took to sell NFT's, you should filter for:
{
...
"actions": ["sell"],
"contractTypes": ["marketplace"]
...
}
This allows us to stay true to the actual infrastructure of the blockchain and enabling a lot more flexibility. We'd use the nft contract type for, say, mint actions.

This is the full selection for contractType:

Contract Types
community - e.g. Gitcoin, JokeDAO
derivatives - e.g. Synthetix, dYdX
exchange - e.g. Uniswap, 0x, Velodrome
lending - e.g. Aave, Compound
marketplace - e.g. OpenSea, etc.
native - e.g. ERC20
nft - e.g. Bored Ape
savings - e.g. PoolTogether
token - e.g. USDC
wallet - e.g. Gnosis Safe, Argent
Copy link
Outline
Filters
This is the full selection for action:
This is the full selection for contractType: