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

# Create an Organisation for Your Agents

> Even working alone, you need an organisation to create agents and fund them. Your tenant, contracts and maps stay exactly where they are.

> [!NOTE]
>
> This page picks up where [Set Up Dev Env](https://docs.terminal3.io/developers/adk/get-started/prerequisites/set-up-dev-env.md) leaves off: you should already have an authenticated `t3n` client and your `tenantDid` in `quickstart.ts`.

## Why a developer working alone needs one

* **Agents pay for their own calls.** When an agent calls a contract for you, the agent's own credit balance is charged — not yours, and not your tenant's. A new agent starts at zero.
* **Only an organisation admin can create an agent or move credit to one.** Creating an agent mints its key inside the TEE and marks the identity as an agent; funding moves your credit to it. Both require you to administer an organisation the agent belongs to. There is no individual-only path.
* **The organisation is a wrapper, not a move.** Your tenant (`z:<your tid>:…`), your registered contracts and your maps stay exactly where they are. The organisation only owns and funds your agents — you don't re-register anything.

By the end of this page you have one organisation, one agent created through it, and that agent funded with **5 credits** from your own balance. The [walkthrough](https://docs.terminal3.io/developers/adk/get-started/walkthrough/what-is-z-namespace.md) then has that agent call your first contract.

**1. Create the organisation (once)**

With the CLI that ships with the SDK — it signs with the same key, from `T3N_API_KEY`:

```bash theme={null}
npx -p @terminal3/t3n-sdk t3n org create --name "My Project" --env testnet --json
# { "organisationDid": "did:t3n:0a1b2c...", "name": "My Project" }
export ORG_DID="did:t3n:0a1b2c..."   # the value printed above
```

Or from `quickstart.ts`. The guard matters: `quickstart.ts` re-runs from the top every time, and creating an organisation is **not idempotent** — every call makes a new one.

```bash theme={null}
cat >> quickstart.ts << 'EOF'

let orgDid = process.env.ORG_DID;
if (!orgDid) {
  orgDid = (await t3n.createOrganisation("My Project")).value;
  console.log(`Created organisation ${orgDid} — run: export ORG_DID="${orgDid}"`);
}
EOF
```

> [!NOTE]
>
> **The SDK returns a `Did` object (`{ value }`), not a string.** Take `.value` before you store, compare or render it — rendering the object in React fails with error #31, "object with keys `{value}`". The same goes for `myOrgs()` and `createAgent().agentDid`.

Already administer an organisation? Use that one instead: `(await t3n.myOrgs()).map(d => d.value)` lists the organisations you belong to. Store the DID either way; never re-create an organisation because you lost its DID.

A new organisation's own balance is **zero**. That's expected — you won't fund agents from it.

**2. Create your agent through it**

```bash theme={null}
npx -p @terminal3/t3n-sdk t3n agent create --org "$ORG_DID" --name "Vault Checker" --env testnet --json
# { "agentDid": "did:t3n:1a2b3c...", "apiKey": "t3n_key_43c0...", "keyId": "43c0...", "organisationDid": "did:t3n:0a1b2c...", ... }
```

Or in `quickstart.ts`, guarded the same way:

```bash theme={null}
cat >> quickstart.ts << 'EOF'

let agentDid = process.env.AGENT_DID;
if (!agentDid) {
  const agent = await t3n.createAgent(orgDid, "Vault Checker");
  agentDid = agent.agentDid.value;
  console.log(`Created agent ${agentDid}`);
  console.log(`run: export AGENT_DID="${agentDid}" AGENT_API_KEY="${agent.apiKey}"`);
}
EOF
```

> [!WARNING]
>
> **The `apiKey` is shown once.** Store it encrypted straight away — it is the agent's only credential and cannot be recovered. The agent calls contracts with this key alone, through `invoke()`; it never opens a session. Keep it out of your repository and logs; the line above prints it only so you can copy it into your shell.

Leave out `--initial-credits` / `initialCredits`. It funds the agent from the **organisation's** balance, which is zero, so creation fails. Fund it from your own balance in the next step instead.

**3. Fund the agent with 5 credits from your own balance**

```bash theme={null}
npx -p @terminal3/t3n-sdk t3n agent fund --agent "$AGENT_DID" --amount 5000000 --note "initial credit" --env testnet
```

In code, use `toBaseUnits` rather than writing the zeros yourself:

```bash theme={null}
cat >> quickstart.ts << 'EOF'

import { toBaseUnits } from "@terminal3/t3n-sdk";

if (process.argv.includes("--fund-agent")) {
  await t3n.fundAgent(agentDid, toBaseUnits(5)); // 5 credits
  console.log(`Funded ${agentDid} with 5 credits`);
}
EOF
npx tsx quickstart.ts --fund-agent
```

* **Amounts are in base units: 1 credit = 1,000,000.** `--amount 5000000` and `toBaseUnits(5)` are both 5 credits — enough for the agent's calls in this walkthrough only, and a small part of the test credits you received at sign-up. The walkthrough uses them up, so top the agent up before anything that calls out to the internet: [Flight Booking](https://docs.terminal3.io/developers/adk/use-cases/flight-booking.md) needs at least 300 credits.
* **Without `--from-org` / `fromOrg`, the credit comes from your own balance.** That's the path for a one-person organisation.
* You must administer an organisation the agent belongs to (creating it there in step 2 made it a member), and your balance must cover the amount.
* **Check your own balance any time** with `formatTokens((await t3n.getBalance()).available)` (`getBalance()` returns `{ available, reserved, … }` in base units) or `npx -p @terminal3/t3n-sdk t3n token balance --env testnet`. Your own calls are metered too: registering, storing, granting, and the session calls each run of `quickstart.ts` makes all come out of your balance.
* **Top up the agent the same way any time.** There is currently no call that shows you an *agent's* balance, and `getUsage()` doesn't list funding transfers, so keep track of what you've funded.
* Never fund yourself: it's refused with "cannot fund yourself", even from the organisation's balance.

**4. Check**

`listAgents` is admin-only and paged with `next_cursor`:

```bash theme={null}
cat >> quickstart.ts << 'EOF'

import { createOrgDataClientFromSession } from "@terminal3/t3n-sdk";

const orgData = createOrgDataClientFromSession(t3n, getNodeUrl());
const { agents } = await orgData.listAgents({ orgDid });
console.log("Agents:", agents.map((a) => `${a.name} (${a.did})`));
EOF
```

Run `npx tsx quickstart.ts` with `ORG_DID`, `AGENT_DID` and `AGENT_API_KEY` exported: it should list your agent and create nothing new.

The agent can't call anything yet — it has an identity and credit, but no permission. You grant it exactly one function of your first contract in [Store, grant and check](https://docs.terminal3.io/developers/adk/get-started/walkthrough/invoke-contract.md).

## What's next

[What is z-namespace?](https://docs.terminal3.io/developers/adk/get-started/walkthrough/what-is-z-namespace.md), then write your first contract. For the CLI-only version of this page, including agent cards, see [Register an Organization-owned Agent](https://docs.terminal3.io/developers/agents/provision-org-agent.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.