GraphQL

**GraphQL** — is a query language for API to the blockchain

GraphQL server is a TON OS built-in component.

## Purpose

* Query blockchain data
* Subscribe to blockchain data updates
* Deploy contracts and send external messages to them

## End-points list

* Free TON network - https://main.ton.dev/graphql
* TON Labs developer network https://net.ton.dev/graphql
* TON OS SE for local testing http://0.0.0.0/graphql (for Windows http://127.0.0.1/graphql or http://localhost/graphql)

## Query schema

The main types - root ("what does"):

* query - retrieving data
* mutation - changing data
* subscription - query to get data about changes depending on events

The main types ("query objects"):

* blocks
* accounts
* messages
* transaction

There are also many other queries (non-root):

Their list and description, please click here.

## Query examples

### Getting account information

```
query{
  accounts(
  filter:{
		id:{
    		eq:"-1:3333333333333333333333333333333333333333333333333333333333333333"
  	}
  }){
    acc_type
    last_paid
    due_payment
    last_trans_lt
    balance
    data
    data_hash
    code
    code_hash
    library
    library_hash
    boc
  }
}

```

* **id** - full address (workchain:address)
* **acc\_type:**

```
0 – uninit (not initialized — account has balance, but no code)
1 – active (account has balance and code)
2 – frozen (account has been frozen)

```

* **last\_paid** — unixtime of the most recent payment
* **last\_trans\_lt** — logical time of last account transaction
* **balance** — the number of tokens on account (note: a non-zero balance is required for deploying a smart contract)
* **data** — contains smart-contract data (if present). Encoded within base64.
* **data\_hash** — data field hash
* **code** — smart contract code (if present). Encoded within base64.
* **code\_hash** — code field hash
* **library** — library code field used in the smart contract (if present)
* **library\_hash** — library field hash
* **boc** — a bag of cells containing information about the account structure. Encoded within base64.

### Getting all transactions of an account

```
{
  transactions(
    filter: {
  		account_addr{
      		eq:"0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13"}
	  	}
    orderBy:[
    	{path:"now",direction:ASC},
  		{path:"lt",direction:ASC}
	]
    limit:2
  )
  {
    id
    now
    lt
  }
}

```

* **account\_addr** - address of an account.
* **now** - the time of the transaction.
* **lt** - logical time. This is a positive 64-bit integer. A component of the TON Blockchain that also plays an important role in message delivery

By default, the result is limited to 50 records. For page-by-page output, Lt (logical time) of the last record can be used in the next query.

Use logical time (lt) of the last entry and repeat the query with the gt “greater than” condition.

```
{
  transactions(
    filter: {
  		account_addr:{
      		eq:"0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13"
      	}
      	lt:	{gt:"0x458b31301"}
	}
    orderBy:[{path:"now",direction:ASC},{path:"lt"}]
    limit:2
  )
  {
    id
    now
    lt
  }
}

```

### Getting all messages of an account

By default, a maximum of 50 entries can be obtained. To get the next 50 entries, created\_lt (logical creation time) of the last entry should be used in the next query.

In the next query, the number of results returned is limited to two.

```
{
  messages(
	  filter:{
		src:{eq:"0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13"}
		created_lt:{gt:"0x0"}
    	OR:{
			dst:{eq:"0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13"}
			created_lt:{gt:"0x0"}
		}
  	  }
	  limit:2
  	  orderBy:[{path:"created_at",direction:ASC},{path:"created_lt"}]
  )
  {
    id
    src
    dst
	created_at
    created_lt
  }
}

```

Result:

```
{
  "data": {
    "messages": [
      {
        "id": "2e80b1b06a8a5340d06627dd3e37f6b2b8436af643c24ff80a2f7840899d8e0e",
        "src": "-1:7777777777777777777777777777777777777777777777777777777777777777",
        "dst": "0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13",
        "created_at": 1593681809,
        "created_lt": "0x451307782"
      },
      {
        "id": "2a0d4e79d8f2d22fc6f3226cf1c972202b5ce8cb709a7d5539b3e7a0e90729ea",
        "src": "0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13",
        "dst": "-1:7777777777777777777777777777777777777777777777777777777777777777",
        "created_at": 1593681814,
        "created_lt": "0x4514efc02"
      }
    ]
  }
}

```

Getting 2 records implies the existence of the following records. To get them, created\_lt should be used and a query with the condition gt (greater than) should be repeated

```
{
  messages(
	  filter:{
			src:{eq:"0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13"}
			created_lt:{gt:"0x4514efc02"}
        OR:{
			dst:{eq:"0:2bb4a0e8391e7ea8877f4825064924bd41ce110fce97e939d3323999e1efbb13"}
			created_lt:{gt:"0x4514efc02"}
	    }
      }
      limit:2
  	  orderBy:[{path:"created_at",direction:ASC},{path:"created_lt"}]
  )
  {
    id
    src
    dst
	created_at
    created_lt
  }
}

```

## Libraries and wrappers

**Query Module** — wrapper on top of the TON Labs GraphQL API.

Languages: Node.js, Rust

## Links

1. Introduction to Access Blockchain Data
2. Query module
3. Description of GraphQl Free TON fields
4. graphql.org - official website

be:GraphQL
de:GraphQL
el:GraphQL
es:GraphQL
fr:GraphQL
ru:GraphQL
tr:GraphQL
uk:GraphQL