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

# Projects

> Each project is an isolated wallet with its own balance, tokens, and transaction history.

# Projects

A **project** is the core organizational unit in Unwall. Each project is an isolated environment that contains a USDC wallet on Base chain, a set of API tokens, and a complete transaction ledger. There is no crossover between projects -- an agent operating in Project A cannot access funds or tokens belonging to Project B.

## What Is a Project?

Every project you create gives you three things:

<CardGroup cols={3}>
  <Card title="USDC Wallet" icon="wallet">
    A custodial wallet on Base chain, powered by Bridge.xyz. This is where your agent's funds live.
  </Card>

  <Card title="API Tokens" icon="key">
    Scoped bearer tokens that your agents use to authenticate. Each token has granular permissions.
  </Card>

  <Card title="Transaction Ledger" icon="receipt">
    A complete history of every deposit, payment, and fee recorded via double-entry accounting.
  </Card>
</CardGroup>

## Balance Model

Every project tracks these balance fields (all values in micro-USDC, where 1 USDC = 1,000,000):

| Field          | Type    | Description                                       |
| -------------- | ------- | ------------------------------------------------- |
| `available`    | integer | USDC the agent can spend right now                |
| `pending`      | integer | USDC in transit or awaiting on-chain confirmation |
| `total_funded` | integer | Cumulative USDC funded into this project          |
| `total_spent`  | integer | Cumulative USDC spent from this project           |

<Note>
  **The Supabase ledger is the source of truth for all balances.** Balance is computed from completed transaction rows via `ledger_get_balance`. Balance is never served from cache when authorizing payments -- it is always fetched fresh to prevent overdraw.
</Note>

### Atomic Operations

Balance modifications use ledger RPC functions with PostgreSQL advisory locks (`pg_advisory_xact_lock`) for per-project serialization. If two concurrent requests attempt to spend the last dollar, only one succeeds. The other receives an "Insufficient balance" error.

## Wallet Address

Each project gets a **Bridge.xyz custodial wallet address** on Base chain for receiving USDC deposits. You can retrieve this address from the dashboard or via the API:

```bash theme={null}
curl https://api.unwall.xyz/v1/stablecoin/address \
  -H "Authorization: Bearer aw_live_xxxxxxxxxxxx"
```

```json Response theme={null}
{
  "chain": "base",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
  "currency": "usdc"
}
```

<Warning>
  Only send **USDC on the Base network** to this address. Sending other tokens or using the wrong chain may result in lost funds.
</Warning>

## Project Status

| Status   | Meaning                                                                          |
| -------- | -------------------------------------------------------------------------------- |
| `active` | Fully operational. Agents can read balances, send payments, and make x402 calls. |
| `paused` | Temporarily suspended. All API tokens for this project return 403 errors.        |
| `closed` | Permanently deactivated. No further operations allowed.                          |

When a project is paused or closed, the token authentication middleware checks the project status and rejects requests before they reach the service layer.

## Project Limits

The number of projects you can create depends on your plan tier:

| Tier        | Monthly Volume   | Max Projects | Transaction Fee |
| ----------- | ---------------- | ------------ | --------------- |
| **Starter** | ≤ \$2,500        | 3            | 2%              |
| **Growth**  | $2,500 – $10,000 | 10           | 1.5%            |
| **Scale**   | > \$10,000       | Unlimited    | 1%              |

<Info>
  Tiers are computed automatically from your monthly transaction volume — no subscriptions required. If your volume drops, existing projects remain active. You cannot create new projects until you are under the limit for your current tier.
</Info>

## Creating a Project

Projects are created through the dashboard at [app.unwall.xyz](https://app.unwall.xyz). Each new project is automatically provisioned with:

1. A Bridge.xyz custodial wallet on Base chain
2. An initial API token (displayed once at creation)
3. A ledger account for double-entry balance tracking

## Next Steps

<CardGroup cols={2}>
  <Card title="Fund Your Project" icon="circle-dollar-to-slot" href="/guides/fund-project">
    Add USDC to your project via on-chain deposit or virtual bank account.
  </Card>

  <Card title="API Tokens" icon="key" href="/concepts/tokens">
    Create scoped tokens with the right permissions for your agents.
  </Card>
</CardGroup>