Skip to content

Commit ce01901

Browse files
victorbwarevictorbware
authored
feat: add docs for solana ws and methods (#1234)
* feat: add docs for solana ws and methods
1 parent 52d7929 commit ce01901

10 files changed

Lines changed: 735 additions & 2 deletions

File tree

‎content/api-reference/pricing-resources/pricing/compute-unit-costs.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,14 @@ For more details, check out the [Compute Units](/docs/reference/compute-units#wh
202202

203203
* Amount will be pro-rated based on bytes streamed. [Contact us](https://www.alchemy.com/contact-sales) for pre-committed bulk discounts.
204204

205+
# Solana: WebSocket Subscriptions
206+
207+
[Solana WebSocket subscriptions](/docs/reference/solana-subscription-api-endpoints) (`accountSubscribe`, `programSubscribe`, `logsSubscribe`, etc.) are priced based on **bandwidth:** the amount of data delivered as part of the stream.
208+
209+
| Bandwidth | CU |
210+
| --------- | ------ |
211+
| 1 byte | .0002 |
212+
205213
# Debug API
206214

207215
| Method | CU | Throughput CU |

‎content/api-reference/websockets/solana-subscription-api-endpoints/account-subscribe.mdx‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: accountSubscribe
3+
description: Subscribe to notifications when one Solana account's lamports or data change.
4+
subtitle: Subscribe to notifications when one Solana account's lamports or data change.
5+
slug: reference/account-subscribe
6+
---
7+
8+
The `accountSubscribe` method opens a stream that emits a notification any time the lamports or data of a specified account change. Pair it with [`accountUnsubscribe`](#unsubscribe) to stop receiving notifications.
9+
10+
# Parameters
11+
12+
* `pubkey`: `string` - Account pubkey, as a base-58 encoded string.
13+
14+
* `config` (optional): `object` - Configuration object containing:
15+
16+
* `commitment`: `string` - The commitment level to use. One of `processed`, `confirmed`, `finalized`. Defaults to `finalized`.
17+
* `encoding`: `string` - Account data encoding. One of `base58`, `base64`, `base64+zstd`, `jsonParsed`. Defaults to `base58`.
18+
19+
# Request
20+
21+
<CodeGroup>
22+
```shell wscat
23+
// initiate websocket stream first
24+
wscat -c wss://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->
25+
26+
// then call subscription
27+
{"jsonrpc":"2.0","id":1,"method":"accountSubscribe","params":["CM78CPUeXjn8o3yroDHxUtKsZZgoy4GPkPPXfouKNH12",{"encoding":"jsonParsed","commitment":"finalized"}]}
28+
```
29+
30+
```javascript @solana/web3.js
31+
import { Connection, PublicKey } from '@solana/web3.js'
32+
33+
const connection = new Connection(
34+
'https://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->',
35+
{
36+
wsEndpoint: 'wss://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->',
37+
commitment: 'finalized'
38+
}
39+
)
40+
41+
const accountPubkey = new PublicKey('CM78CPUeXjn8o3yroDHxUtKsZZgoy4GPkPPXfouKNH12')
42+
43+
const subscriptionId = connection.onAccountChange(
44+
accountPubkey,
45+
(accountInfo, context) => {
46+
console.log('Account update at slot', context.slot, {
47+
lamports: accountInfo.lamports,
48+
owner: accountInfo.owner.toBase58(),
49+
dataLen: accountInfo.data.length
50+
})
51+
},
52+
'finalized'
53+
)
54+
55+
// To unsubscribe later:
56+
// await connection.removeAccountChangeListener(subscriptionId)
57+
```
58+
</CodeGroup>
59+
60+
# Result
61+
62+
<CodeGroup>
63+
```json result
64+
// subscribe response
65+
{"jsonrpc":"2.0","result":23784,"id":1}
66+
67+
// notification
68+
{
69+
"jsonrpc": "2.0",
70+
"method": "accountNotification",
71+
"params": {
72+
"result": {
73+
"context": { "slot": 5199307 },
74+
"value": {
75+
"data": ["11116bv5nS2h3y12kD1yUKeMZvGcKLSjQgX6BeV7u1FrjeJcKfsHRTPuR3oZ1EioKtYGiYxpxMG5vpbZLsbcBYBEmZZcMKaSoGx9JZeAuWf", "base58"],
76+
"executable": false,
77+
"lamports": 33594,
78+
"owner": "11111111111111111111111111111111",
79+
"rentEpoch": 635,
80+
"space": 80
81+
}
82+
},
83+
"subscription": 23784
84+
}
85+
}
86+
```
87+
</CodeGroup>
88+
89+
# Unsubscribe
90+
91+
Use `accountUnsubscribe` with the subscription id returned by `accountSubscribe` to cancel the stream.
92+
93+
* `subscription_id`: `number` - The subscription id to cancel.
94+
95+
<CodeGroup>
96+
```shell wscat
97+
{"jsonrpc":"2.0","id":1,"method":"accountUnsubscribe","params":[subscription_id]}
98+
```
99+
</CodeGroup>
100+
101+
```json result
102+
{"jsonrpc":"2.0","result":true,"id":1}
103+
```
104+
105+
When using `@solana/web3.js`, call `connection.removeAccountChangeListener(subscriptionId)` instead of sending the raw JSON-RPC request.

‎content/api-reference/websockets/solana-subscription-api-endpoints/logs-subscribe.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: logsSubscribe
3+
description: Subscribe to Solana transaction log messages that match a log filter.
4+
subtitle: Subscribe to Solana transaction log messages that match a log filter.
5+
slug: reference/logs-subscribe
6+
---
7+
8+
The `logsSubscribe` method opens a stream that emits a notification any time a transaction is committed and its logs match the supplied filter. Pair it with [`logsUnsubscribe`](#unsubscribe) to stop receiving notifications.
9+
10+
# Parameters
11+
12+
* `filter`: filter criteria for log subscriptions. Accepts one of:
13+
14+
* `"all"` - subscribe to all transactions except simple vote transactions.
15+
* `"allWithVotes"` - subscribe to all transactions including simple vote transactions.
16+
* An object: `{ "mentions": ["<pubkey>"] }` - subscribe to transactions that mention exactly one of the provided base-58 encoded pubkeys.
17+
18+
* `config` (optional): `object` - Configuration object containing:
19+
20+
* `commitment`: `string` - The commitment level. One of `processed`, `confirmed`, `finalized`. Defaults to `finalized`.
21+
22+
# Request
23+
24+
<CodeGroup>
25+
```shell wscat
26+
// initiate websocket stream first
27+
wscat -c wss://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->
28+
29+
// then call subscription
30+
{"jsonrpc":"2.0","id":1,"method":"logsSubscribe","params":[{"mentions":["11111111111111111111111111111111"]},{"commitment":"finalized"}]}
31+
```
32+
33+
```javascript @solana/web3.js
34+
import { Connection, PublicKey } from '@solana/web3.js'
35+
36+
const connection = new Connection(
37+
'https://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->',
38+
{
39+
wsEndpoint: 'wss://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->',
40+
commitment: 'finalized'
41+
}
42+
)
43+
44+
const subscriptionId = connection.onLogs(
45+
new PublicKey('11111111111111111111111111111111'),
46+
(logs, context) => {
47+
console.log('Logs at slot', context.slot, {
48+
signature: logs.signature,
49+
err: logs.err,
50+
logs: logs.logs
51+
})
52+
},
53+
'finalized'
54+
)
55+
56+
// To unsubscribe later:
57+
// await connection.removeOnLogsListener(subscriptionId)
58+
```
59+
</CodeGroup>
60+
61+
# Result
62+
63+
<CodeGroup>
64+
```json result
65+
// subscribe response
66+
{"jsonrpc":"2.0","result":24040,"id":1}
67+
68+
// notification
69+
{
70+
"jsonrpc": "2.0",
71+
"method": "logsNotification",
72+
"params": {
73+
"result": {
74+
"context": { "slot": 5208469 },
75+
"value": {
76+
"signature": "5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv",
77+
"err": null,
78+
"logs": [
79+
"Program 11111111111111111111111111111111 invoke [1]",
80+
"Program 11111111111111111111111111111111 success"
81+
]
82+
}
83+
},
84+
"subscription": 24040
85+
}
86+
}
87+
```
88+
</CodeGroup>
89+
90+
# Unsubscribe
91+
92+
Use `logsUnsubscribe` with the subscription id returned by `logsSubscribe` to cancel the stream.
93+
94+
* `subscription_id`: `number` - The subscription id to cancel.
95+
96+
<CodeGroup>
97+
```shell wscat
98+
{"jsonrpc":"2.0","id":1,"method":"logsUnsubscribe","params":[subscription_id]}
99+
```
100+
</CodeGroup>
101+
102+
```json result
103+
{"jsonrpc":"2.0","result":true,"id":1}
104+
```
105+
106+
When using `@solana/web3.js`, call `connection.removeOnLogsListener(subscriptionId)` instead of sending the raw JSON-RPC request.

‎content/api-reference/websockets/solana-subscription-api-endpoints/program-subscribe.mdx‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: programSubscribe
3+
description: Subscribe to notifications for accounts owned by a Solana program.
4+
subtitle: Subscribe to notifications for accounts owned by a Solana program.
5+
slug: reference/program-subscribe
6+
---
7+
8+
The `programSubscribe` method opens a stream that emits a notification when the lamports or data of any account owned by a given program change. Pair it with [`programUnsubscribe`](#unsubscribe) to stop receiving notifications.
9+
10+
# Parameters
11+
12+
* `pubkey`: `string` - Program pubkey, as a base-58 encoded string.
13+
14+
* `config` (optional): `object` - Configuration object containing:
15+
16+
* `commitment`: `string` - The commitment level. One of `processed`, `confirmed`, `finalized`. Defaults to `finalized`.
17+
* `encoding`: `string` - Account data encoding. One of `base58`, `base64`, `base64+zstd`, `jsonParsed`. Defaults to `base58`.
18+
* `filters`: `array` (optional) - An array of filter objects (`memcmp` and/or `dataSize`) to narrow which program-owned accounts trigger notifications.
19+
20+
<Warning>
21+
`programSubscribe` without filters can produce extremely high volumes of notifications. Use `dataSize` and `memcmp` filters to scope the stream to the accounts you care about.
22+
</Warning>
23+
24+
# Request
25+
26+
<CodeGroup>
27+
```shell wscat
28+
// initiate websocket stream first
29+
wscat -c wss://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->
30+
31+
// then call subscription
32+
{"jsonrpc":"2.0","id":1,"method":"programSubscribe","params":["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",{"encoding":"jsonParsed","filters":[{"dataSize":165}]}]}
33+
```
34+
35+
```javascript @solana/web3.js
36+
import { Connection, PublicKey } from '@solana/web3.js'
37+
38+
const connection = new Connection(
39+
'https://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->',
40+
{
41+
wsEndpoint: 'wss://solana-mainnet.g.alchemy.com/v2/<-- ALCHEMY APP API KEY -->',
42+
commitment: 'finalized'
43+
}
44+
)
45+
46+
const programId = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')
47+
48+
const subscriptionId = connection.onProgramAccountChange(
49+
programId,
50+
({ accountId, accountInfo }, context) => {
51+
console.log('Program account update at slot', context.slot, {
52+
account: accountId.toBase58(),
53+
lamports: accountInfo.lamports,
54+
owner: accountInfo.owner.toBase58()
55+
})
56+
},
57+
'finalized',
58+
[{ dataSize: 165 }]
59+
)
60+
61+
// To unsubscribe later:
62+
// await connection.removeProgramAccountChangeListener(subscriptionId)
63+
```
64+
</CodeGroup>
65+
66+
# Result
67+
68+
<CodeGroup>
69+
```json result
70+
// subscribe response
71+
{"jsonrpc":"2.0","result":24040,"id":1}
72+
73+
// notification
74+
{
75+
"jsonrpc": "2.0",
76+
"method": "programNotification",
77+
"params": {
78+
"result": {
79+
"context": { "slot": 5208469 },
80+
"value": {
81+
"pubkey": "H4vnBqifaSACnKa7acsxstsY1iV1bvJNxsCY7enrd1hq",
82+
"account": {
83+
"data": ["11116bv5nS2h3y12kD1yUKeMZvGcKLSjQgX6BeV7u1FrjeJcKfsHRTPuR3oZ1EioKtYGiYxpxMG5vpbZLsbcBYBEmZZcMKaSoGx9JZeAuWf", "base58"],
84+
"executable": false,
85+
"lamports": 33594,
86+
"owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
87+
"rentEpoch": 636,
88+
"space": 80
89+
}
90+
}
91+
},
92+
"subscription": 24040
93+
}
94+
}
95+
```
96+
</CodeGroup>
97+
98+
# Unsubscribe
99+
100+
Use `programUnsubscribe` with the subscription id returned by `programSubscribe` to cancel the stream.
101+
102+
* `subscription_id`: `number` - The subscription id to cancel.
103+
104+
<CodeGroup>
105+
```shell wscat
106+
{"jsonrpc":"2.0","id":1,"method":"programUnsubscribe","params":[subscription_id]}
107+
```
108+
</CodeGroup>
109+
110+
```json result
111+
{"jsonrpc":"2.0","result":true,"id":1}
112+
```
113+
114+
When using `@solana/web3.js`, call `connection.removeProgramAccountChangeListener(subscriptionId)` instead of sending the raw JSON-RPC request.

0 commit comments

Comments
 (0)