> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caminotreasury.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the fundamental concepts of Camino Treasury

## Overview

Camino Treasury is built around a few key concepts that work together to provide comprehensive treasury management for crypto organizations. Understanding these concepts will help you make the most of the platform.

## Organizations

### What is an Organization?

An organization is the top-level entity in Camino Treasury. It represents your company, DAO, or team and contains all your wallets, transactions, and team members.

<Note>
  Each API key is scoped to a single organization. All data returned by the API is isolated to that organization.
</Note>

### Organization Features

* Centralized management of all treasury operations
* Team member access control
* Audit trail of all activities
* Consolidated reporting across wallets

## Wallets

Wallets are the crypto addresses connected to your organization. Each wallet is identified by its on-chain Ethereum address.

### Wallet Properties

| Property       | Description                              |
| -------------- | ---------------------------------------- |
| **Address**    | Blockchain address (e.g., `0x742d35...`) |
| **Label**      | Human-readable name (1-100 characters)   |
| **Created At** | When the wallet was added                |

<Note>
  Wallet addresses must be unique within an organization. The zero address (`0x0000...0000`) is not allowed.
</Note>

## Recipients

A saved destination address (address book entry). Use recipients to pick a known destination when initiating an outbound transfer instead of pasting a raw address every time.

| Field                    | Description                                                           |
| ------------------------ | --------------------------------------------------------------------- |
| `id`                     | Recipient id (integer)                                                |
| `address`                | 0x-address (lowercase, normalized on write). Unique per organization. |
| `label`                  | Human-readable name (1-100 chars)                                     |
| `createdAt`, `updatedAt` | ISO 8601 timestamps                                                   |

`POST /v1/recipients` creates one (`{ address, label }`); `PATCH /v1/recipients/{id}` updates either field; `DELETE /v1/recipients/{id}` removes it.

## Transfers

`GET /v1/transfers` returns all transfers initiated by the organization under a single unified shape — wallet→wallet, bank→wallet (onramp), and wallet→bank (offramp). Each row has a symmetric `from` and `to` side; either side can be a wallet or a bank account.

| Field                                | Description                                                                                                                                                                                     |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                 | Camino-owned UUID                                                                                                                                                                               |
| `from`, `to`                         | Symmetric sides. Each carries `address`, `bankAccount`, `chainId`, `currency`, `amount`. Exactly one of `address` / `bankAccount` is populated per side.                                        |
| `from.address`, `to.address`         | 0x-address (lowercase) when the side is a wallet, otherwise `null`                                                                                                                              |
| `from.bankAccount`, `to.bankAccount` | Embedded `{ id, bankName, accountOwnerName, accountNumberLast4 }` when the side is a bank account, otherwise `null`. For the full bank record look up the same `id` in `GET /v1/bank-accounts`. |
| `from.chainId`, `to.chainId`         | Chain the wallet side lives on, or `null` for bank sides                                                                                                                                        |
| `from.currency`, `to.currency`       | `"USDC" \| "USDT" \| "USD" \| "C0"`                                                                                                                                                             |
| `from.amount`, `to.amount`           | Human-decimal string in the side's `currency`. They may differ for fiat↔crypto transfers (Bridge fees/rate).                                                                                    |
| `status`                             | `pending \| submitted \| completed \| failed`                                                                                                                                                   |
| `transactionHash`                    | On-chain hash once the wallet-side leg (if any) has been submitted; `null` otherwise                                                                                                            |
| `createdAt`, `updatedAt`             | ISO 8601 timestamps                                                                                                                                                                             |

### Pagination

`GET /v1/transfers` is cursor-paginated. Pass `limit` (1-200, default 50) and optionally `cursor` (from the previous response). The response envelope is `{ data, nextCursor, count }` where `nextCursor` is an opaque string for the next page or `null` when there are no more rows, and `count` is `data.length`.

## Yield

Yield is distributed periodically via the on-chain `YieldDistributor`. Each period, the operator commits a merkle root that allocates yield to holders; holders submit a proof to `claim()` and receive their funds directly to the address baked into the leaf.

`GET /v1/yield/{address}?chainId={n?}` returns `{ data: ClaimEntry[], count }` — each entry is self-contained (it carries its own `chainId` + `distributor`) with a `status` of `claimed` or `unclaimed`. Unpublished, unfinalized, and expired-without-claim periods are dropped server-side, so anything with `status === "unclaimed"` is safe to submit immediately.

`GET /v1/yield/artifacts?periodId={n}` returns the full immutable artifact (root, every leaf, every proof, totals) for a published period. Public — anyone can fetch it and independently verify what's committed on-chain.

## Permissions & Roles

Camino Treasury uses role-based access control (RBAC) to manage team permissions.

### Roles

<CardGroup cols={3}>
  <Card title="Owner" icon="crown">
    **Full Access**

    * All permissions
    * Manage billing
    * Delete organization
    * Add/remove members
  </Card>

  <Card title="Admin" icon="user-shield">
    **Management Access**

    * Manage wallets
    * View all data
  </Card>

  <Card title="Member" icon="user">
    **Read-Only Access**

    * View wallets
    * View balances
    * View the activity feed
  </Card>
</CardGroup>

## Activity & Audit Trail

All actions in Camino Treasury are logged, including:

* Wallet additions and removals
* Transaction creation and status changes
* Team member changes
* Balance updates

## Best Practices

### Security

<CardGroup cols={2}>
  <Card title="Principle of Least Privilege" icon="user-lock">
    Give team members only the permissions they need
  </Card>

  <Card title="Regular Audits" icon="magnifying-glass">
    Review activity logs regularly for suspicious activity
  </Card>

  <Card title="Separate Wallets" icon="wallet">
    Use separate wallets for operations vs. long-term storage
  </Card>

  <Card title="Test First" icon="flask">
    Test with small amounts before large operations
  </Card>
</CardGroup>

### Operations

1. **Label Your Wallets** - Use clear, descriptive labels for easy identification
2. **Monitor Balances** - Regularly check balances across your wallets
3. **Track Everything** - Use the activity feed to maintain a complete audit trail

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/guides/quickstart">
    Set up your first organization and connect wallets
  </Card>

  <Card title="API Integration" icon="code" href="/guides/api-integration">
    Integrate Camino Treasury with your systems
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore the complete API documentation
  </Card>
</CardGroup>

## Glossary

<AccordionGroup>
  <Accordion title="EOA (Externally Owned Account)">
    A blockchain account controlled by a private key, capable of signing transactions directly.
  </Accordion>

  <Accordion title="ERC-20 Token">
    A standard interface for fungible tokens on the Ethereum blockchain.
  </Accordion>

  <Accordion title="C0 Token">
    The treasury-managed token in Camino Treasury. Users deposit USDC to receive C0. Yield is distributed separately via the on-chain `YieldDistributor` — holders submit a merkle proof to `claim()` and receive their share. See `GET /v1/yield/{address}`.
  </Accordion>

  <Accordion title="APY (Annual Percentage Yield)">
    The rate of return earned on an investment over one year, accounting for compound interest.
  </Accordion>

  <Accordion title="Gas Fee">
    The transaction fee paid to execute operations on the blockchain.
  </Accordion>

  <Accordion title="DeFi (Decentralized Finance)">
    Financial services and protocols built on blockchain technology without traditional intermediaries.
  </Accordion>
</AccordionGroup>