# `Cartouche.Solana.Token`
[🔗](https://github.com/zenhive/cartouche/blob/main/lib/cartouche/solana/token.ex#L1)

High-level token operations for Solana: balance queries, transfers,
and ATA management.

Combines RPC calls with PDA derivation and instruction building.
Analogous to `Cartouche.Erc20` on the Ethereum side.

## Examples

    # Get USDC balance for a wallet
    {:ok, balance} = Cartouche.Solana.Token.get_balance(wallet, usdc_mint)

    # Get all token balances
    {:ok, balances} = Cartouche.Solana.Token.get_all_balances(wallet)

    # Build transfer instructions (includes ATA creation if needed)
    instructions = Cartouche.Solana.Token.transfer_instructions(
      from_wallet, to_wallet, mint, 1_000_000, 6
    )

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `transfer_instructions` | 6 | Build token transfer instructions between Solana wallets. | `from_wallet: value`, `to_wallet: value`, `mint: value`, `amount: value`, `decimals: value`, `opts: value` |
| `get_all_balances` | 2 | Get all SPL Token and optionally Token-2022 balances for a Solana wallet. | `wallet: value`, `opts: value` |
| `get_balance` | 3 | Get the balance of a specific token mint for a Solana wallet. | `wallet: value`, `mint: value`, `opts: value` |

# `get_all_balances`

```elixir
@spec get_all_balances(
  <<_::256>>,
  keyword()
) ::
  {:ok,
   [
     %{
       mint: String.t(),
       amount: non_neg_integer(),
       decimals: non_neg_integer(),
       token_account: String.t()
     }
   ]}
  | {:error, term()}
```

Get all token balances for a wallet.

Queries both SPL Token Program and Token-2022 by default.

## Options
- `:include_token_2022` - also query Token-2022 (default: true)

# `get_balance`

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

Get the balance of a specific token for a wallet.

Uses `getTokenAccountsByOwner` with a mint filter and `jsonParsed` encoding.
Sums across all token accounts for the mint (usually just the ATA, but
handles edge cases with multiple accounts).

Returns the raw integer amount, decimals, and mint address.

# `transfer_instructions`

```elixir
@spec transfer_instructions(
  <<_::256>>,
  <<_::256>>,
  <<_::256>>,
  non_neg_integer(),
  non_neg_integer(),
  keyword()
) :: [Cartouche.Solana.Transaction.Instruction.t()]
```

Build instructions for a token transfer between wallets.

Handles ATA derivation for both source and destination. Includes an
idempotent ATA creation for the destination (no-op if it already exists).
Uses `transfer_checked` for safety.

Returns a list of instructions suitable for `Transaction.build_message/3`.

## Options
- `:token_program` - Override the token program (default: SPL Token Program).

---

*Consult [api-reference.md](api-reference.md) for complete listing*