Skip to content

Commit 1616b65

Browse files
zakhar-petukhovzakhar-petukhov
committed
remove duplicated func for creating a client and update the documentation
1 parent 9e0381f commit 1616b65

File tree

3 files changed

+164
-57
lines changed

3 files changed

+164
-57
lines changed

‎README.md‎

Lines changed: 160 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,24 @@
1+
# TonAPI SDK
12

2-
# Description
3+
## Description
34

45
This repository contains [TonAPI](https://tonapi.io) SDK and examples.
56

6-
The native TON's RPC is very low-level.
7-
And it is not suitable for building applications on top of it.
7+
The native TON's RPC is very low-level and is not suitable for building applications on top of it. [TonAPI](https://tonapi.io) aims at speeding up development of TON-based applications and provides an API centered around high-level concepts like Jettons, NFTs and so on, while keeping a way to access low-level details.
88

9-
[TonAPI](https://tonapi.io) aims at speeding up development of TON-based applications and
10-
provides an API centered around high-level concepts like Jettons, NFTs and so on,
11-
keeping a way to access low-level details.
9+
Check out more details at [TonAPI Documentation](https://docs.tonconsole.com/tonapi/rest-api).
1210

13-
Check out more details at [TonAPI Documentation](https://docs.tonconsole.com/tonapi/api-v2).
11+
## Installation
1412

15-
# TonAPI SDK Example
13+
To install the TonAPI SDK, run:
1614

17-
Development of TON-based applications is much easier with TonAPI SDK:
15+
```bash
16+
go get github.com/tonkeeper/tonapi-go
17+
```
18+
19+
## Quick Start
20+
21+
Here's a simple example to get you started:
1822

1923
```go
2024
package main
@@ -28,36 +32,171 @@ import (
2832
)
2933

3034
func main() {
31-
client, err := tonapi.New()
35+
// Create a new client with default settings
36+
// If you want to use testnet, use tonapi.TestnetTonApiURL
37+
// You can use TonAPI.io without a token by passing &tonapi.Security{} as the second parameter,
38+
// but note that TonAPI.io has strict rate limits, so it's better to get a Token from tonconsole.com
39+
// in the TonAPI section - it's completely free
40+
client, err := tonapi.NewClient(tonapi.TonApiURL, &tonapi.Security{})
3241
if err != nil {
3342
log.Fatal(err)
3443
}
35-
account, err := client.GetAccount(context.Background(), tonapi.GetAccountParams{AccountID: "EQBszTJahYw3lpP64ryqscKQaDGk4QpsO7RO6LYVvKHSINS0"})
44+
45+
// Get account information
46+
account, err := client.GetAccount(context.Background(), tonapi.GetAccountParams{
47+
AccountID: "EQBszTJahYw3lpP64ryqscKQaDGk4QpsO7RO6LYVvKHSINS0",
48+
})
3649
if err != nil {
3750
log.Fatal(err)
3851
}
39-
fmt.Printf("Account: %v\n", account.Balance)
52+
53+
fmt.Printf("Account Balance: %v\n", account.Balance)
4054
}
4155
```
4256

43-
Take a look at [TonAPI SDK examples](examples).
57+
## Configuration Options
58+
59+
### Network Selection
60+
61+
You can specify which network to use:
62+
63+
```go
64+
// For mainnet
65+
client, err := tonapi.NewClient(tonapi.TonApiURL, &tonapi.Security{})
66+
67+
// For testnet
68+
client, err := tonapi.NewClient(tonapi.TestnetTonApiURL, &tonapi.Security{})
69+
```
70+
71+
### Authentication
72+
73+
While TonAPI can be used without authentication, it's recommended to obtain an API token to avoid rate limits:
74+
75+
```go
76+
// Using API token (recommended)
77+
token := "your-api-token" // Get your free token from tonconsole.com
78+
client, err := tonapi.NewClient(tonapi.TonApiURL, tonapi.WithToken(token))
79+
```
80+
81+
You can get your free API token from [TON Console](https://tonconsole.com/tonapi/api-keys) in the TonAPI section.
4482

45-
## Rest API
83+
### Custom HTTP Client
4684

47-
You can always find the latest version of TonAPI Rest API documentation at [TonAPI Documentation](https://docs.tonconsole.com/tonapi/api-v2).
85+
You can also use a custom client by using WithClient, where you can, for example, pass a throttled client:
4886

49-
[TonAPI SDK example](examples/tonapi-sdk/main.go) shows how to work with Rest API in golang.
87+
```go
88+
import (
89+
"net/http"
90+
"time"
91+
92+
"github.com/tonkeeper/tonapi-go"
93+
"golang.org/x/time/rate"
94+
)
95+
96+
func main() {
97+
// Create a throttled client
98+
throttledClient := &http.Client{
99+
Transport: throttled.NewTransport(
100+
http.DefaultTransport,
101+
rate.NewLimiter(1, 1)), // Set values according to the rate plan of the token
102+
}
103+
104+
// Use custom client with token
105+
token := "your-api-token"
106+
client, err := tonapi.NewClient(
107+
tonapi.TonApiURL,
108+
tonapi.WithToken(token),
109+
tonapi.WithClient(throttledClient),
110+
)
111+
if err != nil {
112+
// handle error
113+
}
114+
115+
// Use client...
116+
}
117+
```
118+
119+
## Common Operations
120+
121+
### Get Account Information
122+
123+
```go
124+
account, err := client.GetAccount(context.Background(), tonapi.GetAccountParams{
125+
AccountID: "EQBszTJahYw3lpP64ryqscKQaDGk4QpsO7RO6LYVvKHSINS0",
126+
})
127+
```
128+
129+
### Get Transactions
130+
131+
```go
132+
transactions, err := client.GetTransactions(context.Background(), tonapi.GetTransactionsParams{
133+
AccountID: "EQBszTJahYw3lpP64ryqscKQaDGk4QpsO7RO6LYVvKHSINS0",
134+
Limit: 10,
135+
})
136+
```
137+
138+
### Get Jettons
139+
140+
```go
141+
jettons, err := client.GetAccountJettons(context.Background(), tonapi.GetAccountJettonsParams{
142+
AccountID: "EQBszTJahYw3lpP64ryqscKQaDGk4QpsO7RO6LYVvKHSINS0",
143+
})
144+
```
145+
146+
## Error Handling
147+
148+
Always check for errors when making API calls:
149+
150+
```go
151+
result, err := client.GetAccount(context.Background(), params)
152+
if err != nil {
153+
// Check if it's a TonAPI error
154+
if apiErr, ok := err.(*tonapi.Error); ok {
155+
fmt.Printf("API Error: %v\n", apiErr.Error)
156+
} else {
157+
fmt.Printf("Error: %s\n", err.Error())
158+
}
159+
return
160+
}
161+
```
162+
163+
## Rate Limiting
164+
165+
TonAPI has rate limits based on your authentication:
166+
- Anonymous users: Strict rate limits
167+
- API token users: Higher limits based on your plan
168+
169+
For high-volume applications, consider implementing a throttled client as shown in the examples.
170+
171+
## Best Practices
172+
173+
1. Always use an API token for production applications
174+
2. Implement proper error handling for all API calls
175+
3. Use a custom HTTP client with rate limiting for high-volume applications
176+
4. Consider caching frequently accessed data
177+
178+
## Documentation
179+
180+
For complete API documentation, visit the [Documentation](https://docs.tonconsole.com) website.
181+
182+
## Support
183+
184+
For support and questions, join the [TonApi Tech](https://t.me/tonapitech) on Telegram.
185+
186+
## REST API
187+
188+
You can always find the latest version of TonAPI REST API documentation at [TonAPI Documentation](https://docs.tonconsole.com/tonapi/rest-api).
189+
190+
[TonAPI SDK example](examples/tonapi-sdk/main.go) shows how to work with REST API in golang.
50191

51192
## Streaming API
52193

53194
Usually, an application needs to monitor the blockchain for specific events and act accordingly.
54195
TonAPI offers two ways to do it: SSE and Websocket.
55196

56-
The advantage of Websocket is that Websocket can be reconfigured dynamically to subscribe/unsubscribe to/from specific events.
57-
Where SSE has to reconnect to TonAPI to change the list of events it is subscribed to.
197+
The advantage of Websocket is that it can be reconfigured dynamically to subscribe/unsubscribe to/from specific events,
198+
whereas SSE has to reconnect to TonAPI to change the list of events it is subscribed to.
58199

59200
Take a look at [SSE example](examples/sse/main.go) and [Websocket example](examples/websocket/main.go) to see how to work with TonAPI Streaming API in golang.
60201

61-
More details can be found at [TonAPI Streaming API Documentation](https://docs.tonconsole.com/tonapi/streaming-api).
62-
63-
202+
More details can be found at [TonAPI Streaming API Documentation](https://docs.tonconsole.com/tonapi/streaming-api).

‎client.go‎

Lines changed: 1 addition & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ func (s *Security) BearerAuth(ctx context.Context, operationName OperationName,
3333
//
3434
// func main() {
3535
// token := "your-api-token"
36-
// client, err := tonapi.New(tonapi.WithToken(token))
36+
// client, err := tonapi.NewClient(tonapi.TonApiURL, tonapi.WithToken(token))
3737
// if err != nil {
3838
// // handle error
3939
// }
@@ -50,35 +50,3 @@ const TonApiURL = "https://tonapi.io"
5050
// Example:
5151
// client, err := NewClient(tonapi.TestnetTonApiURL)
5252
const TestnetTonApiURL = "https://testnet.tonapi.io"
53-
54-
// You can also use a custom client by using WithClient, where you can, for example, pass a throttled client.
55-
//
56-
// Example:
57-
//
58-
// import (
59-
//
60-
// "github.com/tonkeeper/tonapi-go"
61-
//
62-
// )
63-
//
64-
// func main() {
65-
// throttledClient := &http.Client{
66-
// Transport: throttled.NewTransport(
67-
// http.DefaultTransport,
68-
// rate.NewLimiter(1, 1)), // Set values according to the rate plan of the token
69-
// }
70-
// token := "your-api-token"
71-
// client, err := tonapi.New(tonapi.WithToken(token), tonapi.WithClient(throttledClient))
72-
// if err != nil {
73-
// // handle error
74-
// }
75-
// // use client
76-
// }
77-
78-
// New returns a new Client instance.
79-
func New(sec SecuritySource, opts ...ClientOption) (*Client, error) {
80-
if sec == nil {
81-
sec = &Security{}
82-
}
83-
return NewClient(TonApiURL, sec, opts...)
84-
}

‎tonapi_test.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,9 +54,9 @@ func TestThrottling(t *testing.T) {
5454
var client *Client
5555
var err error
5656
if tt.token == "" {
57-
client, err = New(nil, WithClient(throttledClient))
57+
client, err = NewClient(TonApiURL, &Security{}, WithClient(throttledClient))
5858
} else {
59-
client, err = New(WithToken(tt.token), WithClient(throttledClient))
59+
client, err = NewClient(TonApiURL, WithToken(tt.token), WithClient(throttledClient))
6060
}
6161
if err != nil {
6262
t.Fatalf("failed to init tonapi client: %v", err)
@@ -76,7 +76,7 @@ func TestCustomRequest(t *testing.T) {
7676
http.DefaultTransport,
7777
rate.NewLimiter(1, 1)),
7878
}
79-
client, err := New(nil, WithClient(throttledClient))
79+
client, err := NewClient(TonApiURL, &Security{}, WithClient(throttledClient))
8080
if err != nil {
8181
t.Fatalf("failed to init tonapi client: %v", err)
8282
}

0 commit comments

Comments
 (0)