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>.

RPCX methodtext
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 = value for 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 is null, so filter (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

TypeAccepts
pubkeyA base58 Solana address
signatureA base58 transaction signature
stringAny text
uint64An integer from 0 to 2^64 - 1
int64A signed 64-bit integer
float64A number
booltrue or false
timeA UTC time, as RFC 3339 or YYYY-MM-DD. datetime and timestamp mean the same.
pubkey[]A list of base58 Solana addresses, as a JSON array
signature[]A list of base58 transaction signatures, as a JSON array
string[]A list of texts, as a JSON array
uint64[]A list of integers from 0 to 2^64 - 1, as a JSON array

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, address is a column and wallet is the param.
  • $name also means the param, for example filter 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.

StepFormWhat it does
fromfrom <table>Start from a table. from s = <table> gives it a short name.
filterfilter <condition>Keep rows where the condition is true.
derivederive {<name> = <expr>, ...}Add computed columns and keep the others.
selectselect {<column>, <name> = <expr>, ...}Keep only these columns.
sortsort {<column>, -<column>}Order rows. A leading - sorts descending.
taketake <n> or take <start>..<end>Keep the first n rows. An integer param works: take limit.
groupgroup {<column>, ...} (<pipeline>)Run the inner pipeline once per group, usually aggregate. With sort and take inside, it keeps the top rows per group.
aggregateaggregate {<name> = <function>, ...}Reduce all rows, or each group, to one row.
joinjoin side:left <name> = (from <table> | filter <key>) (==<column>)Join another table, read with its own key or range. side is inner (default), left, right, or full.
windowwindow rows:<a>..<b> (<pipeline>)Compute columns over a sliding frame of rows, in the current sort order.

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

KindFunctions
Aggregatecount this, count_distinct, sum, average, min, max, first, last
Windowrow_number this, rank, rank_dense
Mathmath.round, math.abs, math.floor, math.ceil, math.pow, math.sqrt, math.exp, math.ln, math.log10, math.log
Texttext.lower, text.upper, text.trim, text.ltrim, text.rtrim, text.length, text.extract, text.replace, text.starts_with, text.contains, text.ends_with
Timedate.to_text, date.trunc, date.diff
Otherin (a range, a list, or a list param), as (convert to a type such as DOUBLE or Float64)

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 with raw_sql_not_allowed.
  • A prql header, module, import, type definitions, and annotations. These fail with not_allowed.
  • A let with 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 on live_instructions program == <param>. On live_accounts the key is address, and on live_token_accounts it is owner. 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, or slot >= start && slot < stop. A range without a key reads every block in it, so it may cover at most 3,000 slots. live_blocks has 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_accounts and live_token_accounts hold the state at the time the method runs. They have no ts column, no ranges, and no history.
  • Failed transactions are included. Check the success column.
  • Amounts are raw integers. SOL amounts are in lamports (divide by 1e9). Token amounts are in base units (divide by 10^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. The address column says which one. Use count_distinct sig to count transactions across wallets.
  • Inner instructions are included in live_instructions. stack_height == 1 keeps 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:

ColumnTypeMeaning
addressStringThe address the row was found by. Empty when read by sig, program, or a range.
sigStringTransaction signature
slotUInt64Slot
tsDateTime64(3, 'UTC')Block time

See Live tables for every column.

Examples

The fees and programs of recent transactions of many wallets, failed ones included:

RPCX methodtext
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:

RPCX methodtext
# 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:

RPCX methodtext
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:

RPCX methodtext
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:

RPCX methodtext
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.

CodeLevelWhat to do
dsl_syntaxerrorFix the text at the marked place. The text must start with method <name>(<params>) { and end with }.
dsl_unknown_type, dsl_bad_default, dsl_bad_name, dsl_duplicate_paramerrorFix the param in the header.
dsl_unknown_param, dsl_type_mismatcherrorDeclare the param in the header, or give it a type that fits where it is used.
dsl_raw_sql_not_allowed, dsl_not_allowederrorRemove the s-string or the construct. Use the listed steps and functions.
dsl_compileerrorThe pipeline cannot be built. Read the message at the marked place.
unknown_tableerrorUse one of the nine live tables from list_tables.
live_key_missingerrorAdd a key or a bounded range to the filter right after from live_...: address == <param>, (address | in <list param>), sig == <param>, program == <param> on live_instructions, owner on live_token_accounts, or ts >= from && ts < to on a chain table.
dry_run_failederrorThe method was checked on empty tables and refused, for example because a column does not exist. Read the message.