---
title: "Quickstart"
description: "Make a key, keep it on paper, open a workspace with no account, sign in with the key, make a product and see a test sale. For a person in a browser and for an agent in a terminal."
type: tutorial
audience: both
verified: 2026-11-12
canonical: https://one.ie/docs/quickstart
---
Six steps take you from nothing to a product on sale and a test sale counted.
You do not need an account, an email or a password. A person does it in a
browser; an agent does it in a terminal. Both end in the same place.

**The sale here uses test money.** A new shop takes a Stripe test card until
you connect live Stripe, and that card has no cash value. ONE itself runs on
mainnet: crypto through ONE is real money. To practise with crypto, use
testnet (`--net testnet`) and `one wallet faucet`.

Every command below was run against production on 2026-11-08, while it ran on
testnet, with
`oneie@5.7.3`, the version on npm. Where a step was not re-run that day, it
says which walk proved it.

## The one command

An agent can do all six steps with one command, in an empty folder:

```bash
npx oneie --json --name "My Shop"
```

It makes a key, opens a workspace, puts a product on sale in test mode and
prints a checkout link. Pay that link with the test card
`4242 4242 4242 4242` (any future date, any CVC), then run the same command
again. The second run reads the sale back and prints one link that hands the
business to a person. The first run takes 8 to 14 seconds; most of that is one
server call. Proven on production in walks 4 and 6 (2026-11-03 and 2026-11-06,
[agent path](/docs/agent-path)).

The key lives in `.one/agent.key` in that folder, at mode 0600, and the CLI
writes the `.gitignore` line before the key. Run `npx oneie` again in the same
folder and it picks up where it stopped.

The rest of this page does the same six steps one at a time, so you can see
each part.

## 1. Make a key

A key is 24 words. Your device makes them, and nothing is sent while it does.
ONE never sees the words, so ONE cannot recover them for you.

**As a person.** Open [one.ie/key](/key) and press **Generate**. Twenty-four
words land on this device. The page counts its network requests from the press
to the words: zero. Check it yourself in DevTools, Network tab.

**As an agent.** Write the key to a file:

```bash
npx oneie key new --out key.json --yes-i-accept-plaintext-file --json
```

```json
{"ok":true,"out":"key.json","derivation":"v2",
 "addresses":{"sui":"0x0b0d…21e8","evm":"0xd04b…9021",
   "sol":"FT8N…rwtM","btc":"bc1qtgee…khjq","asi":"fetch1tjh8…xe98"},
 "userIdPub":"0h__K_RW…pZg",
 "receipt":{"tookMs":206,"requests":0}}
```

The words go to `key.json` at mode 0600 and never to your output, because an
agent's output is a model's context and a session log. The flag
`--yes-i-accept-plaintext-file` is required: it says you know the file holds
the key unencrypted. `npx` downloads the package first; the key command itself
opens no connection. To check that, run it under macOS `sandbox-exec` with the
network denied, and `key.json` still appears.

One key gives five addresses: Sui, Ethereum, Solana, Bitcoin and ASI. They
derive by the standard paths (BIP-44 and SLIP-0010), so any standard wallet
that loads the same 24 words with no passphrase shows the same addresses.

## 2. Keep it on paper

Write the 24 words on paper. The paper is the key itself, not a hint at it.
Lose every copy and nobody can bring it back, ONE included.

**As a person.** The page offers three ways to keep it: write the words on
paper, save a key file, or seal a copy with Touch ID on this device. Paper is
the one that outlives every device you own. Until you keep it, the key sits
unencrypted in this browser.

**As an agent.** Read the public side of your key back from the words. The
words go in on stdin, never on the command line, where `ps` and your shell
history would show them:

```bash
jq -r .mnemonic key.json | npx oneie key public --json
```

This prints your public identity and the five addresses, and nothing secret.
To rebuild the key from paper on any machine, with no ONE server in the path:

```bash
npx oneie key recover --json < words.txt
npx -y @oneie/recover          # the standalone tool, same answer
```

[one.ie/recover](/recover) lists all three ways back.

## 3. Open a workspace with no account

A workspace is where your products, sales and agents live.

**As an agent.**

```bash
npx oneie --json init --dir . --name "My Shop" --no-wallet
```

```json
{"ok":true,"workspace":"d797947e-…","url":"https://one.ie/u/d797947e-…",
 "key":"./.one/agent.key (0600, ignored via ./.gitignore)",
 "expires":"2027-02-06T09:52:24.000Z"}
```

That took 10.3 seconds. It made a workspace and a sign-in key for it, with no
account and no email. Three things to know:

- **This is a second key, and a different kind.** The 24 words from step 1
  hold money. The `one-…` key that `init` writes is what you send to sign in
  (step 4). It lasts 90 days by default (`--ttl-days`, up to 365).
- **`init` makes its own wallet unless you pass `--no-wallet`.** It does not
  read the words from step 1. In a terminal it seals the new wallet with a
  passphrase you type; with no terminal, pass `--yes-i-accept-plaintext-file`
  or `--no-wallet`, or it refuses with `wallet_passphrase_unavailable`.
- **`--dir .` keeps the key in this folder.** Without it, `init` writes the
  machine-wide `~/.config/one/key`. `--write-env` also writes `ONE_API_KEY` to
  `.env.local` for your app; the CLI does not read that file.

**As a person.** Sign in (step 4) and ONE makes your workspace for you.

## 4. Sign in with the key

Nothing on this path asks for a password.

**As an agent.** Every call sends the key as a Bearer:
`Authorization: Bearer one-…`. The CLI finds it in `.one/agent.key` in the
current folder (or `ONE_API_KEY`, which wins). Check that it is live:

```bash
npx oneie whoami
```

```
workspace  d797947e-d5f9-46c4-a93b-6ce93741ab66
key        one-***…  (live)
base       https://one.ie
```

The key from `init` and from `npx oneie` acts as its workspace: what it buys,
earns or spends lands in the workspace's own balance. See
[What a Bearer key attests](/docs/authority#what-a-bearer-key-attests).

**As a person.** Open [one.ie/signin](/signin) and sign in with Touch ID or
Face ID (a passkey). On the home page, step 4 of the path signs a fresh
challenge with your key instead.

## 5. Make a product

**As an agent.** Turn the shop on in test mode, then make a product. Prices
are in cents. Send `"status":"active"`, or the product is saved as a draft
nobody can buy.

```bash
WS=d797947e-…   # your workspace from step 3

npx oneie ask storefront:enable \
  --data "{\"slug\":\"$WS\",\"enabled\":true,\"testMode\":true}"

npx oneie ask products:create --data "{\"slug\":\"$WS\",
  \"name\":\"Mug\",\"status\":\"active\",
  \"prices\":[{\"unit_amount\":1250,\"currency\":\"usd\",\"is_default\":true}]}"
```

```json
{"outcome":"result",
 "result":{"pid":"prod_0yy3ocrq8rf3cnuj","ppid":"price_sllqcde1m1d6u15o",
   "name":"Mug","workspace":"d797947e-…"}}
```

Each call took about 3 seconds. The product page is
`https://one.ie/u/<workspace>/shop/<pid>`.

**As a person.** Open **Products** in the sidebar and add one.

## 6. See the test sale

Open the product page and buy it with the test card `4242 4242 4242 4242`.
Then read the count back:

```bash
npx oneie ask storefront:stats --data "{\"slug\":\"$WS\"}"
```

```json
{"outcome":"result",
 "result":{"views":0,"checkouts":0,"purchases":0,"revenue_cents":0}}
```

That is the answer before anyone pays. After the test card pays,
`purchases` reads 1. A printed checkout link is not a sale: the count comes
from Stripe's webhook, never from the page. Walk 4 measured the sale counted
27.7 seconds after the agent's first keystroke, and walk 6 read it back in
1.31 seconds. The payment leg was not re-run on 2026-11-08.

A person sees the same sale under **Sales**.

The money is test money until you connect live Stripe. Then a seller's real
card sales go to the seller's own Stripe account; ONE never holds them.

## The same calls over HTTP

The CLI is a thin client. Any HTTP client can call the same door,
`POST /api/ask/<receiver>`, with the payload under `data`:

```bash
curl -s -X POST https://one.ie/api/ask/storefront:stats \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"data\":{\"slug\":\"$WS\"}}"
```

`npx oneie ask` defaults to `https://api.one.ie`, which serves the same door at
the shorter path `POST /ask/<receiver>`.

To list every receiver, ask `meta:catalog`. To get one receiver's exact
request and response as JSON Schema, ask `meta:schema`:

```bash
npx oneie ask meta:catalog --data '{}'
npx oneie ask meta:schema --data '{"receiver":"products:create"}'
```

Two rules about the request shape:

- **The payload goes under `data`.** Post the fields at the top level and the
  door answers `400 {"error":"envelope_missing", …}`.
- **On `one.ie`, send the Bearer.** With no key and no one.ie page as origin,
  `one.ie/api/ask` answers `403` problem+json, `detail: "direct substrate
  access not permitted"`. A key that matches no row answers
  `401 {"error":"invalid_token", …}`.

## Read `outcome`, not the HTTP status

A call that reached a receiver is **HTTP 200** whether it worked or not. The
verdict is the `outcome` field:

| `outcome` | Means |
|---|---|
| `result` | The receiver ran. `result` holds its answer. Check `result.error` too. |
| `dissolved` | Nothing handled it: an unknown receiver, or no handler wired. |
| `failure` | Refused on authority. `result` names the action required and your role. |

A receiver that ran and rejected its input comes back as `outcome: "result"`
with an `error` inside `result`. Only an authority refusal is `failure`:

```json
{"outcome":"failure",
 "result":{"error":"forbidden","receiver":"world:update-thing",
   "required":"manage_things","callerRole":"agent"}}
```

Every refusal name, and which fix it implies, is in [Errors](/docs/errors).

## Known limits

- **The key from `npx oneie` and `init` expires** after 90 days by default.
  Revoke it early with `world:revoke-key`.
- **Opening a workspace is rate-limited** to 5 a minute per IP. Open one and
  reuse its key.
- **Moving value needs a person.** An agent key can sell, and can buy credits
  with crypto (real money on mainnet). A receiver that moves value to someone else
  (`wallet:transfer`, `market:escrow` and the rest) answers `grant_required`
  until a signed-in owner approves it through `agents:approve`.
- **An agent key cannot manage people.** It is refused the member, client and
  workspace management receivers. That needs a person signed in, or a
  person's key from `npx oneie login`.
- **`POST /api/signal/<receiver>` is not a developer door.** It needs the
  server-to-server secret and answers `401` to an agent key. Use `ask`.
- **In a Cloudflare Worker, import the SDK by subpath:**
  `import { SubstrateClient } from "@oneie/sdk/client"`. Pass
  `baseUrl: "https://one.ie"`, or the SDK aims at `http://localhost:4321`
  outside production.

## Next

- [Agent path](/docs/agent-path) — the nine stops, walked on production, with the numbers
- [Wallets](/docs/wallets) — five chains from one key, and agent wallets
- [Payments](/docs/payments) — card sales to your own Stripe, crypto on mainnet, practice on testnet
- [Authority](/docs/authority) — what a key may do, and why
- [CLI](/docs/cli) — every command