Arweave GraphQL Guide
Introduction
This guide is intended as a reference for developer's interested in leveraging Arweave GraphQL endpoints, e.g. arweave.net/graphql. GraphQL endpoints are currently the most robust method of querying for transaction/block metadata on Arweave.
Data Structures
The Data Structures section describes the anatomy of queries. There are several examples that provide context on how to traverse GraphQL. If you want to learn about the GraphQL structure at a more granular level, check out the arweave.dev/graphql Docs tab.
Transaction Structures
Full GraphQL Object
The following is the full GraphQL structure. In most scenarios, you won't need the entire object; however, if you do want the entire metadata of Arweave transactions, you may retrieve it with the following query.
query {
transactions {
cursor
edges {
node {
id
anchor
signature
recipient
owner {
address
key
}
fee {
winston
ar
}
quantity {
winston
ar
}
data {
size
type
}
tags {
name
value
}
block {
id
timestamp
height
previous
}
parent {
id
}
}
}
}
}Transaction IDs
Probably the most common use of GraphQL is to retrieve Transaction IDs. Note: upon accessing Transaction IDs via GraphQL, you can retrieve associated data via the arweave-js "getData()" function.
query {
transactions {
edges {
node {
id
}
}
}
}Arweave Tags
Sometimes, you may need to access the tags embedded in a given Arweave transaction. In this example you can retrieve both the tag name and the value as an array.
query {
transactions {
edges {
node {
id
tags {
name
value
}
}
}
}
}Block Metadata
If you're curious to access details specific to a transaction's block, you can retrieve its block number, mining date, block hash, and the previous block hash.
query {
transactions {
edges {
node {
block {
id
timestamp
height
previous
}
}
}
}
}Payment Data
If you're interested in retrieving payment-related data, you may access the mining fee, the amount paid for the transaction, who received the AR ("0" for data-only transactions), as well as the address that intially sent the AR.
query {
transactions {
edges {
node {
id
recipient
owner {
address
key
}
fee {
winston
ar
}
quantity {
winston
ar
}
}
}
}
}Block Structures
Full GraphQL Object
The following is the full GraphQL structure. In most scenarios, you won't need the entire object; however, if you do want the entire metadata of each Arweave block, you may retrieve it with the following query. Please bear in mind: the Arweave block queried does not contain transaction metadata.
query {
blocks {
edges {
cursor
node {
id
timestamp
height
previous
}
}
}
}Query Structures
The Query Structures section describes the ways in which you may retrieve transactions and blocks with GraphQL. The examples provided may be demoed on arweave.dev/graphql by copy and pasting the provided example queries.
Transaction Structures
Pagination
There are three components to paginatiion queries. First, when retrieving the GraphQL object, always make sure to retrieve the cursor. The cursor is used in queries to traverse to the next page. Second, specify the amount of elements to output by using the "first" key. When "first" is 5, the result set will include 5 transactions. And finally, specify the "after" string (i.e. the "cursor" from the previous page) to fetch the subsequent page.
query {
transactions(first: 5, after: "WyIyMDIwLTA5LTIzVDE2OjQ0OjE0LjY5MloiLDFd") {
edges {
cursor
node {
id
}
}
}
}By Transaction ID
You may retrieve one or more transactions by specifying their IDs in an array.
query {
transactions(ids: ["G-1t0Lqysin897HC3IV8xu_Mr884B-Mo5YEnlhUH54k"]) {
edges {
node {
id
}
}
}
}By Recipients
You may retrieve one or more recipients by specifying their address(es) in an array.
query {
transactions(recipients:["M6w588ZkR8SVFdPkNXdBy4sqbMN0Y3F8ZJUWm2WCm8M"]) {
edges {
node {
id
}
}
}
}By Owners
You may retrieve one or more owners by specifying their address(es) in an array.
query {
transactions(owners:["M6w588ZkR8SVFdPkNXdBy4sqbMN0Y3F8ZJUWm2WCm8M"]) {
edges {
node {
id
}
}
}
}By Tags
You may retrieve transactions via tag name/value pairs.
To look up transactions by a single tag, you may structure your query as follows:
query {
transactions(
tags: {
name: "Content-Type",
values: ["text/html"]
}
) {
edges {
node {
id
}
}
}
}Alternatively, look up transactions using multiple tags like so:
query {
transactions(
tags: [
{
name: "Content-Type",
values: ["text/html"]
},
{
name: "User-Agent",
values: ["ArweaveAutoDPL/0.1"]
}
]
) {
edges {
node {
id
}
}
}
}By Block Height
If you wish to retrieve transactions from given block numbers, you may specify a block height range. The following is an example of how to retrieve all transaction IDs from the genesis block to block #10.
query {
transactions(block: {min: 0, max: 10}) {
edges {
node {
id
}
}
}
}Sorting
If you wish to sort transactions by block height, you may specify the sort order with HEIGHT_DESC or HEIGHT_ASC.
HEIGHT_DESC orders them in descending order, with the most recent and unconfirmed/pending transactions appearing first:
query {
transactions(sort: HEIGHT_DESC) {
edges {
node {
id
}
}
}
}HEIGHT_ASC orders them in ascending order (oldest first):
query {
transactions(sort: HEIGHT_ASC) {
edges {
node {
id
}
}
}
}Block Structures
Pagination
By applying the cursor to the "after" parameter, you may retrieve blocks that were submitted after the current block. Please bear in mind: if you are sorting by HEIGHT_ASC, The blocks retrieved will be blocks prior to the current block.
query {
transactions(first: 5, after: "WyIyMDIwLTA5LTIzVDE2OjQ0OjE0LjY5MloiLDFd") {
edges {
cursor
node {
id
}
}
}
}By Block ID
You may retrieve one or more blocks by specifying their IDs in an array.
query {
blocks(ids: ["J08jRl2S5X0a-wF9bnLvsD_MgEsWpBMttBOWgxpiAdtbi75_HCFCg1M-necyFSD4"]) {
edges {
cursor
node {
id
timestamp
height
previous
}
}
}
}Block Range
You may utilize the height parameter with a "min" and "max" value. This will return blocks within a specified range. The following is an example that retrieves blocks 587540 to 587550:
query {
blocks(height: {
min: 587540,
max: 587550
}) {
edges {
cursor
node {
id
timestamp
height
previous
}
}
}
}Sorting
If you wish to sort blocks by block height, you may specify the sort order with HEIGHT_DESC or HEIGHT_ASC.
HEIGHT_DESC orders them in descending order, with the most recent blocks appearing first:
query {
blocks(sort: HEIGHT_DESC) {
edges {
cursor
node {
id
timestamp
height
previous
}
}
}
}HEIGHT_ASC orders them in ascending order (oldest first).
query {
blocks(sort: HEIGHT_ASC) {
edges {
cursor
node {
id
timestamp
height
previous
}
}
}
}