Skip to main content
This page picks up where Set Up Dev Env 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 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:
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.
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

Or in quickstart.ts, guarded the same way:
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

In code, use toBaseUnits rather than writing the zeros yourself:
  • 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 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:
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.

What’s next

What is z-namespace?, then write your first contract. For the CLI-only version of this page, including agent cards, see Register an Organization-owned Agent.