AnchorPy

0.21.0 verified Fri Apr 17 auth: no python

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.

pip install anchorpy

Common errors

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

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

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

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

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())