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

Associated Token Account (ATA) utilities for Solana.

An ATA is the canonical token account for a (wallet, mint) pair. It is
a PDA derived with seeds `[wallet, token_program_id, mint]` under the
Associated Token Account Program.

## Examples

    iex> {pub, _} = Cartouche.Solana.Keys.from_seed(<<1::256>>)
    iex> mint = Cartouche.Solana.Programs.wrapped_sol_mint()
    iex> {ata, bump} = Cartouche.Solana.ATA.find_address(pub, mint)
    iex> byte_size(ata) == 32 and bump >= 0 and bump <= 255
    true

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `create_idempotent` | 4 | Build an idempotent Associated Token Account create instruction. | `payer: value`, `wallet: value`, `mint: value`, `opts: value` |
| `create` | 4 | Build an Associated Token Account create instruction that fails if the ATA already exists. | `payer: value`, `wallet: value`, `mint: value`, `opts: value` |
| `find_address` | 3 | Derive the associated token account PDA for a wallet and mint. | `wallet: value`, `mint: value`, `opts: value` |

# `create`

```elixir
@spec create(&lt;&lt;_::256&gt;&gt;, &lt;&lt;_::256&gt;&gt;, &lt;&lt;_::256&gt;&gt;, keyword()) ::
  Cartouche.Solana.Transaction.Instruction.t()
```

Build an instruction to create an ATA. Fails if it already exists.

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

# `create_idempotent`

```elixir
@spec create_idempotent(&lt;&lt;_::256&gt;&gt;, &lt;&lt;_::256&gt;&gt;, &lt;&lt;_::256&gt;&gt;, keyword()) ::
  Cartouche.Solana.Transaction.Instruction.t()
```

Build an instruction to create an ATA, succeeding even if it already exists.

This is the preferred variant for most use cases - it is a no-op if the
ATA already exists.

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

# `find_address`

```elixir
@spec find_address(&lt;&lt;_::256&gt;&gt;, &lt;&lt;_::256&gt;&gt;, keyword()) ::
  {&lt;&lt;_::256&gt;&gt;, non_neg_integer()}
```

Derive the associated token account address for a wallet + mint.

Pure computation (no RPC call). Returns `{ata_address, bump_seed}`.

## Options
- `:token_program` - Override the token program (default: SPL Token Program).
  Pass `Programs.token_2022_program()` for Token-2022 mints.

---

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