Writing RPCX Methods
Write methods in the RPCX method language: the header and params, the pipeline, the correctness rules, and the validation report.
A method is plain text in the RPCX method language. It has a header with the name and params, then a pipeline that starts from a table and shapes the rows. Save it with a name and it becomes callable as rpcx_<name>.
method txsFor(wallets: pubkey[] "Accounts", from: time, to: time) { from live_transactions filter (address | in wallets) && ts >= from && ts < to sort {-ts}}Your coding agent can write the method for you through the RPCX MCP server. This page lists the rules it follows, so you can read and check its work. RPCX does not accept SQL.
The header
method <name>(<param>, <param>, ...) {- The name is 1 to 64 letters, digits, or underscores. You call the method as
rpcx_<name>. - Each param is
name: type. Add= valuefor a default and a double-quoted string for a description:limit: uint64 = 10 "How many wallets". - A param is required unless it has a default or a
?after its name:wallet?: pubkey. A?param that a call leaves out isnull, sofilter (wallet == null || user == wallet)makes the filter optional. See Optional filters. - Params may span several lines, and a trailing comma is allowed.
- Lines that start with
#are comments.
Param types
A default is a number, a double-quoted string, true, or false. A list param holds up to 1,000 values. Use it with in: filter (address | in wallets).
Params in the body
- A bare name that matches a param means the param. In
filter address == wallet,addressis a column andwalletis the param. $namealso means the param, for examplefilter fee >= $min_fee.- When a column has the same name as a param, write
this.<column>for the column.
The pipeline
The body is a pipeline. Each line is one step, and each step works on the rows from the step before. The language is based on PRQL. The Method language reference lists every step, function, and operator with an example.
There is no distinct step. To keep one row per value, use group {<column>} (take 1).
let names a relation or a function you use later in the method.
Functions
Arguments follow the function name without parentheses, for example date.trunc "hour" ts or math.round 2 x. In the dashboard, the Code tab completes table names, columns, params, and functions as you type.
Operators: ==, !=, >, >=, <, <=, &&, ||, !, +, -, *, /, // (integer division), %, ?? (use the right side when the left is null), and ~= (regex match). Strings use double quotes.
Not allowed
- Raw SQL, including s-strings such as
s"...". These fail withraw_sql_not_allowed. - A
prqlheader,module,import,typedefinitions, and annotations. These fail withnot_allowed. - A
letwith the same name as a param.
Rules for live tables
These rules decide whether a method runs, what it costs, and whether its numbers are right.
1. Give every read a key or a range, right after from
Every read of a live table needs, in the filter right after from, one of these:
- A key:
address == <param>for any address (a wallet, a program, a pool, a mint, or a token account),sig == <param>for one transaction, or onlive_instructionsprogram == <param>. Onlive_accountsthe key isaddress, and onlive_token_accountsit isowner. For many values, use(address | in <list param>)or a literal list(address | in ["A...", "B..."]). - A bounded range, on a chain table:
ts >= from && ts < to, orslot >= start && slot < stop. A range without a key reads every block in it, so it may cover at most 3,000 slots.live_blockshas no key and is always read by a range.
Other conditions can join it with &&. A key or range under || or !, or in a later step, does not count. Without one, Validate refuses the method with live_key_missing. A table you join needs its own key or range inside the joined pipeline.
2. Add a time range to every read by address
With a key, add ts >= from && ts < to with time params. The range only narrows what RPCX reads, so it makes the run faster and cheaper. Without it, RPCX reads every transaction of the address that it has. Very busy accounts, such as programs, the USDC mint, or the System Program, have a lot of transactions, so a read of one of them reads a lot of data even in a short range.
3. Read many addresses in one call
Pass the addresses as one list param, such as wallets: pubkey[], and filter with (address | in wallets). RPCX reads all of them in the same run. Do not call a method once per wallet. There is no cap on the number of transactions a run reads, but a run has 30 seconds.
Other rules the data needs
- Live data only. The chain tables hold the latest Solana data, up to the newest blocks. Older history is not available, so a range that starts earlier returns only the rows RPCX still has.
- Account tables are current state.
live_accountsandlive_token_accountshold the state at the time the method runs. They have notscolumn, no ranges, and no history. - Failed transactions are included. Check the
successcolumn. - Amounts are raw integers. SOL amounts are in lamports (divide by
1e9). Token amounts are in base units (divide by10^decimals). - One row per requested address. A transaction that touches two of your addresses shows once for each of them in tables read by
address. Theaddresscolumn says which one. Usecount_distinct sigto count transactions across wallets. - Inner instructions are included in
live_instructions.stack_height == 1keeps only top-level instructions.
Columns the chain tables share
live_signatures, live_transactions, live_instructions, live_logs, live_sol_balance_changes, and live_token_balance_changes all have these columns:
See Live tables for every column.
Examples
The fees and programs of recent transactions of many wallets, failed ones included:
method recentFees(wallets: pubkey[] "Wallets", from: time, to: time, limit: uint64 = 100 "Max rows") { from live_transactions filter (address | in wallets) && ts >= from && ts < to select {address, ts, sig, success, fee, programs} sort {-ts} take limit}Transactions per hour for many wallets, with a computed column:
# Transactions per wallet and hour.method hourlyTxs(wallets: pubkey[] "Wallets", from: time "Start (UTC)", to: time "End (UTC)") { from live_signatures filter (address | in wallets) && ts >= from && ts < to derive {hour = date.trunc "hour" ts} group {address, hour} ( aggregate {txs = count this} ) sort {address, hour}}The net token flow of many wallets, per mint:
method tokenFlows(wallets: pubkey[] "Wallets", from: time, to: time) { from live_token_balance_changes filter (address | in wallets) && ts >= from && ts < to filter owner == address group {address, mint} (aggregate {net = sum change, txs = count_distinct sig})}The SOL balance of many wallets right now:
method solBalances(wallets: pubkey[] "Wallets") { from live_accounts filter (address | in wallets) select {address, sol = lamports / 1000000000}}The most called programs in a short time range, read without a key:
method topPrograms(from: time "Start, inclusive", to: time "End, exclusive", n: uint64 = 20 "Rows") { from live_instructions filter ts >= from && ts < to && stack_height == 1 group {program} (aggregate {calls = count this, txs = count_distinct sig}) sort {-calls} take n}This range has no key, so it may cover at most 3,000 slots. Pick a short range.
More examples, one or two per table, are on Examples by table.
Save the method
In the dashboard, select New Method and paste the whole method into the Code tab. The name and params come from the header. You can also type only the pipeline in the Code tab and select Untitled method to give it a name. Then select Save. You call the method as rpcx_<name>. Run in the dashboard needs the saved method, so save before you run it.
Saving the same name again creates a new version and makes it active. Deleting a method deletes every version, and calls to it fail from then on. See Calling RPCX methods.
Read the validation report
Validate returns errors, which block the method, and warnings, which do not. In the dashboard, each problem is marked in the code. Fix every error. Read every warning.
Problems in the method text itself have a line and column, and their codes start with dsl_ in the report.