Quickstart

claude "Read https://one.ie/docs/quickstart.md. Explain Quickstart back to me in five lines, then name the one thing on that page I am most likely to get wrong."

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.

Everything here runs on test money. ONE is on testnet until launch: a sale is paid with a Stripe test card, and crypto is testnet crypto. Neither has cash value.

Every command below was run against production on 2026-11-08 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:

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).

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 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:

npx oneie key new --out key.json --yes-i-accept-plaintext-file --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:

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:

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

one.ie/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.

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

{"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:

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.

As a person. Open one.ie/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.

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}]}"

{"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:

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

{"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. 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:

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:

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:

{"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.

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 testnet crypto. 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 — the nine stops, walked on production, with the numbers
• Wallets — five chains from one key, and agent wallets
• Payments — test money, card sales to your own Stripe, crypto on testnet
• Authority — what a key may do, and why
• CLI — every command