> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List IDL Versions

> List every IDL version Parsed Events has for a Solana program, with the slot at which each version became active.

The path parameters, response schema, and examples on this page are generated from the OpenAPI definition.

List IDL Versions returns the history of a program's interface from the IDL catalog that Parsed Events and [Parsed Streams](https://www.helius.dev/docs/parsed-streams.md) use to decode instructions. Each item is one version, identified by the slot at which it became active. Items are sorted oldest first, so the last item is the current version.

Pass any `slot` from the response to [Get IDL](https://www.helius.dev/docs/api-reference/parsed-events/idl.md) to fetch that version's IDL document. The [Orb explorer](https://www.helius.dev/docs/orb/explore-programs.md) uses these endpoints to show program IDLs.

## Use Cases

* **Track interface changes.** Poll List IDL Versions for a program you depend on. When a new version appears, fetch it and the previous one with Get IDL and compare their `instructions`. A new admin or authority instruction is worth a security review.
* **Check catalog coverage.** A `404` means the catalog has no IDL for the program. Programs such as SPL Token are decoded by built-in decoders instead and also return `404`.

## Example: Detect a New IDL Version

This script lists a program's IDL versions, fetches the latest two, and prints the instructions that were added or removed:

```javascript diff-idl-versions.js theme={"system"}
const API_KEY = process.env.HELIUS_API_KEY;

if (!API_KEY) {
  console.error("Missing HELIUS_API_KEY.");
  process.exit(1);
}

const BASE = "https://mainnet.helius-rpc.com/v1/parsed-events/idl";
const PROGRAM_ID = "KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD";

async function get(path) {
  const response = await fetch(`${BASE}/${path}?api-key=${API_KEY}`);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  return response.json();
}

const versions = await get(PROGRAM_ID);
if (versions.length < 2) {
  console.log("Fewer than two IDL versions; nothing to compare.");
  process.exit(0);
}

const [previous, latest] = versions.slice(-2);
const [before, after] = await Promise.all([
  get(`${PROGRAM_ID}/${previous.slot}`),
  get(`${PROGRAM_ID}/${latest.slot}`),
]);

const names = (idl) => new Set(idl.instructions.map((ix) => ix.name));
const beforeNames = names(before);
const afterNames = names(after);

console.log(`Comparing slot ${previous.slot} with slot ${latest.slot}`);
console.log("Added:", [...afterNames].filter((name) => !beforeNames.has(name)));
console.log("Removed:", [...beforeNames].filter((name) => !afterNames.has(name)));
```

To detect changes over time, store the `slot` of the last version you have seen and compare against it on each poll.

## Credits

Each request costs **10 credits** and is available on all plans. The example above makes three requests, so it costs 30 credits. See [Credits](https://www.helius.dev/docs/billing/credits.md#parsed-events).

## Errors

| Status | When |
| - | - |
| `400` | `programId` isn't a valid base58 address. |
| `401` | The API key is missing or invalid. The body is plain text: `Unauthorized`. |
| `404` | The catalog has no IDL for the program. |

Other errors return a JSON body with an `error` message, such as `{"error": "no IDLs found for program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"}`.

## Request Parameters

**programId** `string` *required*

Program address, base58-encoded.


## OpenAPI

````yaml openapi/parsed-events.yaml GET /v1/parsed-events/idl/{programId}
openapi: 3.0.3
info:
  title: Parsed Events
  version: 0.1.0
  description: Parse Solana transactions and parsed transaction history with Parsed Events.
servers:
  - url: https://mainnet.helius-rpc.com
security:
  - ApiKeyQuery: []
paths:
  /v1/parsed-events/idl/{programId}:
    get:
      tags:
        - Parsed Events
      summary: List IDL Versions
      description: >-
        List every IDL version Parsed Events has for a program, oldest first.
        Each version is identified by the slot at which it became active.
      operationId: listIdlVersionsParsedEvents
      parameters:
        - $ref: '#/components/parameters/ProgramId'
      responses:
        '200':
          description: The program's IDL versions, sorted by `slot` ascending.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdlVersion'
              examples:
                default:
                  summary: Kamino Lend (first 3 of 43 versions)
                  value:
                    - slot: 182747476
                      sources:
                        - anchor
                    - slot: 205509752
                      sources:
                        - anchor
                    - slot: 206074074
                      sources:
                        - anchor
        '400':
          description: '`programId` isn''t a valid address.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                default:
                  value:
                    error: 'invalid program id: notanaddress: String is the wrong size'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: >-
            The catalog has no IDL for the program. Programs that Parsed Events
            decodes with built-in decoders, such as SPL Token, return `404`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                default:
                  value:
                    error: >-
                      no IDLs found for program
                      TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
components:
  parameters:
    ProgramId:
      name: programId
      in: path
      required: true
      description: Program address, base58-encoded.
      schema:
        type: string
        example: KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD
  schemas:
    IdlVersion:
      type: object
      description: One IDL version of a program.
      required:
        - slot
        - sources
      properties:
        slot:
          type: integer
          format: uint64
          description: >-
            Slot at which this IDL version became active. Pass it to Get IDL to
            fetch this version.
        sources:
          type: array
          description: >-
            Where Parsed Events found this version. Values include `anchor`,
            `program_metadata`, and `github`, and more may be added. A version
            can have more than one source.
          items:
            type: string
    ErrorResponse:
      type: object
      description: Request-level error response.
      properties:
        error:
          type: string
          description: Error message.
  responses:
    Unauthorized:
      description: The API key is missing or invalid. The body is plain text.
      content:
        text/plain:
          schema:
            type: string
          examples:
            default:
              value: Unauthorized
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.