AnchorPy

0.21.0 · active · verified Fri Apr 17

AnchorPy is the official Python client for interacting with Solana programs built using the Anchor framework. It provides a robust and type-safe way to connect to Solana clusters, manage wallets, deserialize IDLs, and call program instructions. Currently at version 0.21.0, it sees regular updates with minor versions released every few weeks or months to keep pace with the evolving Solana ecosystem.

Common errors

```
TypeError: object PublicKey is not callable
```
cause Attempting to call `PublicKey` as a function without providing a byte array or string argument (e.g., `PublicKey()`)

fix You must provide an argument to `PublicKey` constructor, like `PublicKey('YourProgramIdHere')` or `PublicKey(bytes_array)`.
```
anchorpy.error.ProgramError: Failed to send transaction: Transaction simulation failed: Error processing instruction...
```
cause This is a generic error from the Solana cluster indicating an issue within the program logic, missing accounts, insufficient funds for an account, or an incorrect instruction argument.

fix Examine the full error message from the cluster for specifics. Debug your program logic, ensure all required accounts are provided and correctly ordered, and verify the payer wallet has enough SOL.
```
RuntimeWarning: coroutine '...' was never awaited
```
cause An asynchronous function (coroutine) was called but its execution was not awaited, meaning Python did not wait for its completion.

fix Add the `await` keyword before the coroutine call (e.g., `await program.rpc['instruction']()`). Ensure your code is running within an `asyncio` event loop.
```
NameError: name 'Commitment' is not defined
```
cause The `Commitment` enum was used without being imported, or it was imported from an old, incorrect path.

fix Ensure `from solana.rpc.commitment import Commitment` is at the top of your file.

Warnings

breaking The `Program` and `Provider` constructors no longer accept `payer` or `http_client` arguments (since v0.20.0). `payer` is now passed directly to `rpc` methods.
Fix: Remove `payer` and `http_client` from `Program` and `Provider` initialization. Pass `payer` directly to program RPC methods (e.g., `program.rpc['my_instruction'](accounts={'payer': my_keypair.public_key}, signers=[my_keypair])`).
breaking The `Commitment` enum import path changed in `solana-py` to `from solana.rpc.commitment import Commitment` from `solana.rpc.core.Commitment`.
Fix: Update `Commitment` imports to `from solana.rpc.commitment import Commitment`.
breaking The `Provider` constructor argument `skip_preflight` and `preflight_commitment` were replaced by a single `opts` argument (which takes a `Commitment` value).
Fix: Replace `skip_preflight=True, preflight_commitment=Commitment('processed')` with `opts=Commitment('processed')`.
gotcha AnchorPy operations are asynchronous. Forgetting to `await` calls or not running them within an `asyncio` event loop will lead to `RuntimeWarning: coroutine '...' was never awaited` or program freezes.
Fix: Ensure all async function calls are prefixed with `await` and the entry point is run with `asyncio.run(main())` or similar.
gotcha When signing transactions, the `signers` argument for RPC calls expects a list of `solana.keypair.Keypair` objects, not just public keys or `Wallet` objects.
Fix: Ensure `signers=[my_keypair]` is passed, where `my_keypair` is an actual `Keypair` instance, for any accounts that need to sign the transaction (e.g., the fee payer, or mutable accounts).

Install

pip install anchorpy Install stable version

Imports

Provider
```
from anchorpy import Provider
```
Wallet
```
from anchorpy import Wallet
```
Program
wrong:
```
from anchorpy.client import Program
```
correct:
```
from anchorpy import Program
```
Program is now typically imported directly from the top-level `anchorpy` package.
Idl
```
from anchorpy import Idl
```
Commitment
wrong:
```
from solana.rpc.core import Commitment
```
correct:
```
from solana.rpc.commitment import Commitment
```
Moved from `solana.rpc.core` to `solana.rpc.commitment` in `solana-py` v0.20.0, impacting `anchorpy` users.
PublicKey
```
from solana.publickey import PublicKey
```
Keypair
```
from solana.keypair import Keypair
```

Quickstart

This quickstart demonstrates how to establish a connection to a Solana cluster, initialize a wallet (using an ephemeral keypair for demonstration), load a placeholder IDL, and create an AnchorPy Program client. Remember to replace `SOLANA_RPC_URL` and `program_id` with your actual values, and provide a valid IDL for your program. Interactions with Solana programs are asynchronous and require `asyncio`.

import asyncio
import os
from solana.keypair import Keypair
from solana.publickey import PublicKey
from solana.rpc.api import Client
from solana.rpc.commitment import Commitment
from anchorpy import Provider, Wallet, Program, Idl

async def main():
    # 1. Setup Solana client and provider
    rpc_url = os.environ.get("SOLANA_RPC_URL", "https://api.devnet.solana.com")
    connection = Client(rpc_url)

    # For a real wallet, you would load a private key
    # e.g., from an environment variable or file.
    # For this example, we use a dummy keypair (not funded).
    payer = Keypair.generate() # Generate a new ephemeral keypair
    wallet = Wallet(payer)
    provider = Provider(connection, wallet, opts=Commitment("confirmed"))

    # 2. Define a placeholder program ID and a minimal IDL
    #    (Replace with your actual program ID and IDL)
    program_id = PublicKey("11111111111111111111111111111111") # Example: System Program
    idl_json = {
        "version": "0.1.0",
        "name": "my_anchor_program",
        "instructions": [] # Populate with your program's instructions
    }
    idl = Idl.from_json(idl_json)

    # 3. Instantiate the Program client
    program = Program(idl, program_id, provider)

    print(f"Successfully connected to Solana cluster: {rpc_url}")
    print(f"Using wallet public key: {provider.wallet.public_key}")
    print(f"Interacting with program ID: {program.program_id}")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →