@spec get_account_info(
  <<_::256>>,
  keyword()
) :: {:ok, map() | nil} | {:error, term()}

Get account info for a pubkey. Returns nil if the account doesn't exist.

Options

• :commitment - :processed, :confirmed, or :finalized
• :encoding - :base64 (default), :base58, :"base64+zstd", :json_parsed

@spec get_balance(
  <<_::256>>,
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Get the SOL balance (in lamports) for an account.

Options

• :commitment - :processed, :confirmed, or :finalized

@spec get_block_height(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}

Get the current block height.

@spec get_health(keyword()) :: :ok | {:error, term()}

Check node health. Returns :ok if healthy, {:error, ...} if unhealthy.

@spec get_latest_blockhash(keyword()) ::
  {:ok, %{blockhash: binary(), last_valid_block_height: non_neg_integer()}}
  | {:error, term()}

Get the latest blockhash and its last valid block height.

@spec get_minimum_balance_for_rent_exemption(
  non_neg_integer(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, term()}

Get the minimum balance for rent exemption for a given data size.

@spec get_multiple_accounts(
  [<<_::256>>],
  keyword()
) :: {:ok, [map() | nil]} | {:error, term()}

Get account info for multiple pubkeys (max 100).

Options

• :commitment, :encoding - same as get_account_info/2

@spec get_recent_prioritization_fees(
  [<<_::256>>],
  keyword()
) ::
  {:ok, [%{slot: non_neg_integer(), prioritization_fee: non_neg_integer()}]}
  | {:error, term()}

Get recent prioritization fees. Pass account addresses to see fees for transactions locking those accounts.

@spec get_signature_statuses(
  [String.t()],
  keyword()
) :: {:ok, [map() | nil]} | {:error, term()}

Get the statuses of transaction signatures (max 256).

Options

• :search_transaction_history - Search beyond recent status cache (default: false)

@spec get_slot(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}

Get the current slot.

@spec get_token_account_balance(
  <<_::256>>,
  keyword()
) ::
  {:ok,
   %{
     amount: non_neg_integer(),
     decimals: non_neg_integer(),
     ui_amount_string: String.t()
   }}
  | {:error, term()}

Get the token balance for an SPL Token account.

Returns the raw integer amount, decimal precision, and ui_amount_string (a human-readable formatted string provided by the RPC node, e.g. "1.5" for 1500000 with 6 decimals).

@spec get_token_accounts_by_owner(<<_::256>>, keyword(), keyword()) ::
  {:ok, [%{pubkey: String.t(), account: map()}]} | {:error, term()}

Get all token accounts owned by a wallet.

Accepts :mint (specific token) or :program_id (all tokens under a program). If both are present, :mint takes precedence. Raises ArgumentError if neither is provided.

Uses jsonParsed encoding by default for structured token account data.

Examples

get_token_accounts_by_owner(wallet, mint: usdc_mint)
get_token_accounts_by_owner(wallet, program_id: Programs.token_program())

@spec get_transaction(
  String.t(),
  keyword()
) :: {:ok, map() | nil} | {:error, term()}

Get a transaction by its signature.

Returns nil if the transaction is not found.

Options

• :commitment - :confirmed or :finalized (:processed is NOT supported)
• :encoding - :json (default), :json_parsed, :base64, :base58

@spec get_version(keyword()) ::
  {:ok, %{solana_core: String.t(), feature_set: non_neg_integer()}}
  | {:error, term()}

Get the node version.

@spec request_airdrop(<<_::256>>, non_neg_integer(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Request an airdrop of SOL (devnet/testnet only).

Returns the airdrop transaction signature.

@spec send_and_confirm(
  Cartouche.Solana.Transaction.t() | binary(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Send a transaction and poll for confirmation.

Options

• :commitment - Confirmation level to wait for (default: :confirmed)
• :timeout - Max time to wait in ms (default: 30_000)
• :poll_interval - Poll interval in ms (default: 500)
• All options from send_transaction/2

@spec send_rpc(binary(), list(), keyword()) ::
  {:ok, term()} | {:error, send_rpc_error()}

Send a raw JSON-RPC request to the Solana node.

Options:

• :solana_node - Override the node URL
• :timeout - Request timeout in ms (default: 30000)
• :id - JSON-RPC request ID (default: auto-generated)

Examples

iex> Cartouche.Solana.RPC.send_rpc("getSlot", [])
{:ok, 123456789}

iex> match?({:error, {:invalid_params, %Jason.EncodeError{}}}, Cartouche.Solana.RPC.send_rpc(<<255>>, []))
true

iex> match?({:error, {:invalid_params, %Protocol.UndefinedError{}}}, Cartouche.Solana.RPC.send_rpc("getSlot", [self()]))
true

@spec send_transaction(
  binary() | Cartouche.Solana.Transaction.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Send a signed transaction to the network.

Accepts a Cartouche.Solana.Transaction struct or raw serialized bytes.

Options

• :encoding - :base64 (default) or :base58
• :skip_preflight - Skip preflight checks (default: false)
• :preflight_commitment - Commitment for preflight simulation
• :max_retries - Max retries before giving up

Returns the transaction signature (Base58 string).

@spec simulate_transaction(
  binary() | Cartouche.Solana.Transaction.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Simulate a transaction without submitting it.

Returns simulation result including logs, compute units consumed, and errors.