Parameters

owner

string

REQUIRED

The owner's Sui address

coin_type

string

REQUIRED

The type names for the coin (e.g., 0x2::sui::SUI)

Returns

balance

object

The balance information for the requested coin type

coinType

string

The type of the coin (e.g., 0x2::sui::SUI)

balance

string

Shows the total balance of the coin in its smallest unit

Request

1
grpcurl -proto ./sui/rpc/v2/state_service.proto -H "x-token: abcde123456789" -d '{
2
  "owner": "0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c",
3
  "coin_type": "0x2::sui::SUI"
4
}' docs-demo.sui-mainnet.quiknode.pro:9000 sui.rpc.v2.StateService/GetBalance

1
grpcurl -proto ./sui/rpc/v2/state_service.proto -H "x-token: abcde123456789" -d '{
2
  "owner": "0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c",
3
  "coin_type": "0x2::sui::SUI"
4
}' docs-demo.sui-mainnet.quiknode.pro:9000 sui.rpc.v2.StateService/GetBalance

1
package main
2

3
import (
4
	"context"
5
	"crypto/tls"
6
	"encoding/json"
7
	"fmt"
8
	"log"
9
	"time"
10

11
	"google.golang.org/grpc"
12
	"google.golang.org/grpc/credentials"
13
	"google.golang.org/protobuf/encoding/protojson"
14

15
	pb "sui-grpc/sui/rpc/v2" // Your Generated .pb.go files path
16
)
17

18
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
19
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
20
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
21
// token will be : abcde123456789
22

23
var (
24
	token    = "YOUR_TOKEN_NUMBER"
25
	endpoint = "YOUR_QN_ENDPOINT:9000"
26
)
27

28
// Auth structure for x-token
29
type auth struct {
30
	token string
31
}
32

33
func (a *auth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
34
	return map[string]string{"x-token": a.token}, nil
35
}
36
func (a *auth) RequireTransportSecurity() bool {
37
	return true
38
}
39

40
func main() {
41
	creds := credentials.NewTLS(&tls.Config{})
42
	opts := []grpc.DialOption{
43
		grpc.WithTransportCredentials(creds),
44
		grpc.WithPerRPCCredentials(&auth{token}),
45
	}
46

47
	conn, err := grpc.Dial(endpoint, opts...)
48
	if err != nil {
49
		log.Fatalf("Failed to connect: %v", err)
50
	}
51
	defer conn.Close()
52

53
	client := pb.NewStateServiceClient(conn)
54

55
	owner := "0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c"
56
	coinType := "0x2::sui::SUI"
57

58
	// Build request with field mask
59
	req := &pb.GetBalanceRequest{
60
		Owner:    &owner,
61
		CoinType: &coinType,
62
	}
63

64
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
65
	defer cancel()
66

67
	resp, err := client.GetBalance(ctx, req)
68
	if err != nil {
69
		log.Fatalf("GetBalance failed: %v", err)
70
	}
71

72
	// Pretty print the response
73
	marshaler := protojson.MarshalOptions{
74
		UseProtoNames:   true,
75
		EmitUnpopulated: true,
76
		Indent:          "  ",
77
	}
78

79
	jsonBytes, err := marshaler.Marshal(resp)
80
	if err != nil {
81
		log.Fatalf("Failed to marshal: %v", err)
82
	}
83

84
	var pretty map[string]interface{}
85
	if err := json.Unmarshal(jsonBytes, &pretty); err != nil {
86
		log.Fatalf("Failed to parse JSON: %v", err)
87
	}
88

89
	out, _ := json.MarshalIndent(pretty, "", "  ")
90
	fmt.Println(string(out))
91
}
92

1
package main
2

3
import (
4
	"context"
5
	"crypto/tls"
6
	"encoding/json"
7
	"fmt"
8
	"log"
9
	"time"
10

11
	"google.golang.org/grpc"
12
	"google.golang.org/grpc/credentials"
13
	"google.golang.org/protobuf/encoding/protojson"
14

15
	pb "sui-grpc/sui/rpc/v2" // Your Generated .pb.go files path
16
)
17

18
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
19
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
20
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
21
// token will be : abcde123456789
22

23
var (
24
	token    = "YOUR_TOKEN_NUMBER"
25
	endpoint = "YOUR_QN_ENDPOINT:9000"
26
)
27

28
// Auth structure for x-token
29
type auth struct {
30
	token string
31
}
32

33
func (a *auth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
34
	return map[string]string{"x-token": a.token}, nil
35
}
36
func (a *auth) RequireTransportSecurity() bool {
37
	return true
38
}
39

40
func main() {
41
	creds := credentials.NewTLS(&tls.Config{})
42
	opts := []grpc.DialOption{
43
		grpc.WithTransportCredentials(creds),
44
		grpc.WithPerRPCCredentials(&auth{token}),
45
	}
46

47
	conn, err := grpc.Dial(endpoint, opts...)
48
	if err != nil {
49
		log.Fatalf("Failed to connect: %v", err)
50
	}
51
	defer conn.Close()
52

53
	client := pb.NewStateServiceClient(conn)
54

55
	owner := "0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c"
56
	coinType := "0x2::sui::SUI"
57

58
	// Build request with field mask
59
	req := &pb.GetBalanceRequest{
60
		Owner:    &owner,
61
		CoinType: &coinType,
62
	}
63

64
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
65
	defer cancel()
66

67
	resp, err := client.GetBalance(ctx, req)
68
	if err != nil {
69
		log.Fatalf("GetBalance failed: %v", err)
70
	}
71

72
	// Pretty print the response
73
	marshaler := protojson.MarshalOptions{
74
		UseProtoNames:   true,
75
		EmitUnpopulated: true,
76
		Indent:          "  ",
77
	}
78

79
	jsonBytes, err := marshaler.Marshal(resp)
80
	if err != nil {
81
		log.Fatalf("Failed to marshal: %v", err)
82
	}
83

84
	var pretty map[string]interface{}
85
	if err := json.Unmarshal(jsonBytes, &pretty); err != nil {
86
		log.Fatalf("Failed to parse JSON: %v", err)
87
	}
88

89
	out, _ := json.MarshalIndent(pretty, "", "  ")
90
	fmt.Println(string(out))
91
}
92

1
import * as grpc from '@grpc/grpc-js';
2
import * as protoLoader from '@grpc/proto-loader';
3
import * as path from 'path';
4

5
// Configuration
6
const PROTO_PATH = path.join(__dirname, 'protos/proto/sui/rpc/v2/state_service.proto');
7

8
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
9
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
10
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
11
// token will be : abcde123456789
12

13
const endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
14
const token = 'abcde123456789';
15

16
// Load protobuf definitions
17
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
18
  keepCase: true,
19
  longs: String,
20
  enums: String,
21
  defaults: true,
22
  oneofs: true,
23
  includeDirs: [path.join(__dirname, 'protos/proto')],
24
});
25

26
const proto = grpc.loadPackageDefinition(packageDefinition) as any;
27
const StateService = proto.sui.rpc.v2.StateService;
28

29
// Create secure client
30
const client = new StateService(endpoint, grpc.credentials.createSsl());
31

32
// Add token metadata
33
const metadata = new grpc.Metadata();
34
metadata.add('x-token', token);
35

36
// Request payload
37
const request = {
38
  owner: '0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c',
39
  coin_type: '0x2::sui::SUI',
40
};
41

42
// Perform gRPC call
43
client.GetBalance(request, metadata, (err: grpc.ServiceError | null, response: any) => {
44
  if (err) {
45
    console.error('gRPC Error:', {
46
      code: err.code,
47
      message: err.message,
48
      details: err.details,
49
    });
50
  } else {
51
    console.log('GetBalance Response:');
52
    console.log(JSON.stringify(response, null, 2));
53
  }
54
});
55

1
import * as grpc from '@grpc/grpc-js';
2
import * as protoLoader from '@grpc/proto-loader';
3
import * as path from 'path';
4

5
// Configuration
6
const PROTO_PATH = path.join(__dirname, 'protos/proto/sui/rpc/v2/state_service.proto');
7

8
// Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
9
// For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
10
// endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
11
// token will be : abcde123456789
12

13
const endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
14
const token = 'abcde123456789';
15

16
// Load protobuf definitions
17
const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
18
  keepCase: true,
19
  longs: String,
20
  enums: String,
21
  defaults: true,
22
  oneofs: true,
23
  includeDirs: [path.join(__dirname, 'protos/proto')],
24
});
25

26
const proto = grpc.loadPackageDefinition(packageDefinition) as any;
27
const StateService = proto.sui.rpc.v2.StateService;
28

29
// Create secure client
30
const client = new StateService(endpoint, grpc.credentials.createSsl());
31

32
// Add token metadata
33
const metadata = new grpc.Metadata();
34
metadata.add('x-token', token);
35

36
// Request payload
37
const request = {
38
  owner: '0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c',
39
  coin_type: '0x2::sui::SUI',
40
};
41

42
// Perform gRPC call
43
client.GetBalance(request, metadata, (err: grpc.ServiceError | null, response: any) => {
44
  if (err) {
45
    console.error('gRPC Error:', {
46
      code: err.code,
47
      message: err.message,
48
      details: err.details,
49
    });
50
  } else {
51
    console.log('GetBalance Response:');
52
    console.log(JSON.stringify(response, null, 2));
53
  }
54
});
55

1
import grpc
2
import json
3
from google.protobuf.json_format import MessageToDict
4
from sui.rpc.v2 import state_service_pb2, state_service_pb2_grpc
5

6

7
def get_balance():
8

9
    # Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
10
    # For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
11
    # endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
12
    # token will be : abcde123456789
13

14
    endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
15
    token = 'abcde123456789';
16

17
    channel = grpc.secure_channel(endpoint, grpc.ssl_channel_credentials())
18
    stub = state_service_pb2_grpc.StateServiceStub(channel)
19

20
    owner = "0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c"
21
    coin_type = "0x2::sui::SUI"
22

23
    request = state_service_pb2.GetBalanceRequest(
24
        owner=owner,
25
        coin_type=coin_type
26
    )
27

28
    metadata = [("x-token", token)]
29

30
    return stub.GetBalance(request, metadata=metadata)
31

32

33
def parse_response_to_json(response):
34
    return json.dumps(
35
        MessageToDict(response, preserving_proto_field_name=True),
36
        indent=2
37
    )
38

39

40
def main():
41
    try:
42
        response = get_balance()
43
        print(parse_response_to_json(response))
44
    except grpc.RpcError as e:
45
        print(f"{e.code().name}: {e.details()}")
46

47

48
if __name__ == "__main__":
49
    main()
50

1
import grpc
2
import json
3
from google.protobuf.json_format import MessageToDict
4
from sui.rpc.v2 import state_service_pb2, state_service_pb2_grpc
5

6

7
def get_balance():
8

9
    # Quicknode endpoints consist of two crucial components: the endpoint name and the corresponding token
10
    # For eg: QN Endpoint: https://docs-demo.sui-mainnet.quiknode.pro/abcde123456789
11
    # endpoint will be: docs-demo.sui-mainnet.quiknode.pro:9000  {9000 is the port number for Sui gRPC}
12
    # token will be : abcde123456789
13

14
    endpoint = 'docs-demo.sui-mainnet.quiknode.pro:9000';
15
    token = 'abcde123456789';
16

17
    channel = grpc.secure_channel(endpoint, grpc.ssl_channel_credentials())
18
    stub = state_service_pb2_grpc.StateServiceStub(channel)
19

20
    owner = "0xac5bceec1b789ff840d7d4e6ce4ce61c90d190a7f8c4f4ddf0bff6ee2413c33c"
21
    coin_type = "0x2::sui::SUI"
22

23
    request = state_service_pb2.GetBalanceRequest(
24
        owner=owner,
25
        coin_type=coin_type
26
    )
27

28
    metadata = [("x-token", token)]
29

30
    return stub.GetBalance(request, metadata=metadata)
31

32

33
def parse_response_to_json(response):
34
    return json.dumps(
35
        MessageToDict(response, preserving_proto_field_name=True),
36
        indent=2
37
    )
38

39

40
def main():
41
    try:
42
        response = get_balance()
43
        print(parse_response_to_json(response))
44
    except grpc.RpcError as e:
45
        print(f"{e.code().name}: {e.details()}")
46

47

48
if __name__ == "__main__":
49
    main()
50

Don't have an account yet?

Create your Quicknode endpoint in seconds and start building

Get started for free