Address Lookup Tables

Address Lookup Tables are found and read in bulk with getProgramAccounts or getProgramAccountsV2 on the Address Lookup Table program.

Access

Queries go through getProgramAccounts or getProgramAccountsV2 with AddressLookupTab1e1111111111111111111111111 as the first parameter. The endpoint and the API key are the same as every other Solana RPC call. There is no separate method, hostname or add-on.

Answers come from an in-memory index, not a disk scan. No filter is required, and the 256 MB scan-results cap of a disk scan does not apply. Batch requests (a JSON array of calls) are not served: one call per HTTP request.

Rate limits

The budget is shared per API key. Address Lookup Table queries count together with every other getProgramAccounts and getProgramAccountsV2 call on that key, whichever program they address. A Nexus key sending 50 calls per second against other programs has 25 calls per second left for table queries.

There is no cap on open requests; only the rate is counted. The plan's total requests-per-second limit also applies. See Plans & Limits.

Over the rate, the response is HTTP 429 with code -32005 and the message Rate limit exceeded (gpa: 25/sec) on Blade Runner or Rate limit exceeded (gpa: 75/sec) on Nexus. It carries no Retry-After header and no rate-limit headers. The window is one whole second. See Gateway errors.

One known table

A table whose address is already known is read with getAccountInfo or getMultipleAccounts with encoding: "jsonParsed". That is a plain account read: it is not an index query and does not count against the getProgramAccounts budget.

getProgramAccounts on the Address Lookup Table program is for finding tables by content (authority, size, addresses, status) or for walking all tables.

Account layout

Account size is 56 + 32 × N bytes. A table with 4 addresses is 184 bytes.

Filters

memcmp compares at one fixed offset, so a table that holds an address at an unknown position matches only a filter for that position. There is no "contains" filter.

Filters combine with AND. memcmp bytes may be base58 (default) or base64 via memcmp.encoding.

Examples

getProgramAccounts on the tables controlled by one authority, with no account data returned:

curl "https://rpc-newyork.constant-k.com/?api-key=YOUR_API_KEY" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccounts",
    "params": [
      "AddressLookupTab1e1111111111111111111111111",
      {
        "filters": [
          { "memcmp": { "offset": 22, "bytes": "DStdNqtygUnfNwkHNrEhsPWwN7hqXrYrMJ8JMkLvidjT" } }
        ],
        "dataSlice": { "offset": 0, "length": 0 }
      }
    ]
  }'

dataSlice with length: 0 returns no data, so the answer carries only the table addresses and account metadata. The response is trimmed to one account:

[
  {
    "account": {
      "data": ["", "base64"],
      "executable": false,
      "lamports": 2171520,
      "owner": "AddressLookupTab1e1111111111111111111111111",
      "rentEpoch": 18446744073709551615,
      "space": 184
    },
    "pubkey": "1AjuJovi8byYxtUPyFna86jaRipDgVeX4TCXbkWNZxg"
  }
]

getProgramAccountsV2 returns one page of tables with the layout decoded:

curl "https://rpc-newyork.constant-k.com/?api-key=YOUR_API_KEY" \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccountsV2",
    "params": [
      "AddressLookupTab1e1111111111111111111111111",
      {
        "encoding": "jsonParsed",
        "filters": [{ "dataSize": 184 }],
        "limit": 1,
        "withContext": true
      }
    ]
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "context": { "slot": 457692691 },
    "value": {
      "accounts": [
        {
          "account": {
            "data": {
              "parsed": {
                "info": {
                  "addresses": [
                    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
                    "SysvarRent111111111111111111111111111111111",
                    "Ce6TQqeHC9p8KetsN6JsjHK7UTZk7nasjjnr7XxXp9F1",
                    "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"
                  ],
                  "authority": "DStdNqtygUnfNwkHNrEhsPWwN7hqXrYrMJ8JMkLvidjT",
                  "deactivationSlot": "18446744073709551615",
                  "lastExtendedSlot": "306248204",
                  "lastExtendedSlotStartIndex": 0
                },
                "type": "lookupTable"
              },
              "program": "address-lookup-table",
              "space": 184
            },
            "executable": false,
            "lamports": 2171520,
            "owner": "AddressLookupTab1e1111111111111111111111111",
            "rentEpoch": 18446744073709551615,
            "space": 184
          },
          "pubkey": "1AjuJovi8byYxtUPyFna86jaRipDgVeX4TCXbkWNZxg"
        }
      ],
      "paginationKey": "1AjuJovi8byYxtUPyFna86jaRipDgVeX4TCXbkWNZxg"
    }
  }
}

paginationKey is the cursor for the next page. It is passed back as paginationKey on the next call, and is null on the last page.

Parameters

Result size and freshness

getProgramAccounts answers up to 1 GB of matched account data. Above that it returns -32012 with scan aborted: The accumulated scan results exceeded the limit. getProgramAccountsV2 pages through any size, so walking every table uses it with limit up to 10,000 and paginationKey. Results are narrowed with filters and dataSlice.

If the index falls behind the chain, a getProgramAccountsV2 call with changedSinceSlot returns -32005 with data.numSlotsBehind until the index catches up.

Errors

See Errors for every code and its fix.