# ONE

> Your agent can sell and be paid. ONE is payment infrastructure for
> agents: a key your own machine makes, five wallets, a shop, payment
> links, cards at Stripe's cost, and USDC on Sui with no ONE fee. Four
> surfaces over one receiver catalog: HTTP, CLI (`npx oneie`), MCP
> (`@oneie/mcp`) and SDK (`@oneie/sdk`).

The prompt to hand any agent, the same on the page and in the CLI:
`Your agent can sell and be paid. Read https://one.ie/llms.txt, then run: npx oneie`

**Network: read it before money moves, never from this file.**
`curl -s https://pay.one.ie/status` → `"network"`, or `<meta name="one:network">`
on https://one.ie. While it says `testnet`, every money line below moves test
money (Sui testnet, Stripe test mode) with no cash value, and the faucet and
the 4242 card work only there. When it says `mainnet`, the money is real: ask
your person before you pay.

## The eight beats

one.ie tells it in eight beats. The page, the chat, the film and
`npx oneie` walk the same eight, in this order.

1. **The sale.** A payment card a customer pays: on a web page, in a chat,
   behind any link an agent sends.
2. **The call.** Your person says what they sell; you make a product and a
   payment link for each: `npx oneie --product "Mug=12.50"`. Reading a
   website into products has not been walked end to end yet.
3. **Cards.** Card, Apple Pay and Google Pay pay into the seller's own
   Stripe, once it is connected. The seller pays Stripe's cost; ONE's fee
   on a card sale is 0.
4. **Crypto.** USDC on Sui, wallet to wallet, straight to the seller's
   wallet by default (ONE holds it only if the seller switches escrow on).
   ONE takes 0%. The network charges its own small fee, in SUI.
5. **The key.** Your machine makes it; the press sends nothing over the
   network. It signs you in with no password and no email, and it makes
   the wallets. The 24 words on paper bring all of it back, without ONE.
6. **Your agents.** `npx oneie` gives an agent its own key, five
   addresses, a group and a shop (on a Mac, or at a terminal where a
   passphrase can be typed). Its owner sets a monthly credit limit for
   ONE's paid services, and only the owner can raise it; it does not cap
   the agent's own wallet.
7. **Do it now.** Make a sale and read back the receipt (step 4 below).
8. **The gift.** ONE charges nothing for the key, the wallets, the links
   or a wallet-to-wallet send; the network's own fee is paid in SUI. One thing costs money: Sold, a course where people and
   agents learn to sell together, $100 once with a month of the community
   (https://one.ie/sold). It is priced for a person, not an agent.

## If you are an agent: your first lesson

Key, workspace, product, sale, test money, credits, a model call, a read-back.
Steps 1–3 and 5–10 ran on production on 2026-11-07 with `oneie@5.7.3` and no
person in the loop; the test sale in step 4 ran on 2026-11-06 with a stranger
paying (https://one.ie/docs/agent-path). Times are from those runs.

1. Make your signing key. Nothing goes over the network (66 ms).

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

   stdout: `{"ok":true,"out":"key.json","addresses":{"sui":…,"evm":…,"sol":…,"btc":…,"asi":…},"userIdPub":…}`.
   The 24 words go into key.json (mode 0600), never to stdout. Recovery is
   paper: give the words to your person or keep them where you keep secrets.
   ONE never holds them and cannot give them back. Check offline:
   `jq -r .mnemonic key.json | npx oneie key public --json`.

2. Be born: a workspace, its key, five wallets, a shop and a $1 test product
   (9–13 s). Run it in an empty folder:

   ```
   npx -y oneie --json --name "<your name>"
   ```

   stdout: `{"ok":…,"workspace":"<ws>","steps":[…],"next":…}`. The key is
   written to `.one/agent.key` (0600, git-ignored) and expires after 90 days
   (`/api/provision/agent`; `init --ttl-days` up to 365). Run it again to resume.
   Its wallet is sealed in the Apple Keychain or with a passphrase typed at a
   terminal; a headless shell is refused by name (`wallet: no Apple Keychain
   here and no terminal…`). Headless instead: `npx oneie --json init
   --no-wallet` (workspace + key at `~/.config/one/key`; not walked end to end).

3. Make a product, with your person's yes on the name and the price:

   ```
   npx oneie --json ask products:create --data '{"slug":"<ws>","name":"30-minute call","status":"active","prices":[{"unit_amount":1000,"currency":"usd"}]}'
   ```

   Answers `{pid, ppid}`. Its page is `https://one.ie/u/<ws>/shop/<pid>`.

4. Sell it. Shop checkout runs in Stripe test mode: a buyer pays with
   `4242 4242 4242 4242`, any future date, any CVC, and the sale is counted
   (nothing → counted sale under 30 s). A test sale grants no credits.
   Card setup for a shop, in one call (owner-only, test mode only):
   `npx oneie --json ask storefront:test-cards --data '{}'` → `stage`
   `checking` (call again) · `live` · `paid` (a €10 test payment went
   through). Refusals: `test_mode_only`, `country_not_supported` (IE only).

5. Get test money (3–5 s; one ask per address per 24 h):

   ```
   npx oneie --json wallet faucet <addresses.sui> --chain sui --network testnet
   ```

   0.05 test SUI. Read `results[].success`; a refusal carries `reason`:
   `rate_limited`, `treasury_empty` or `not_configured`.

6. Ask for a price (x402). No `tx_digest` means "quote me":

   ```
   curl -s -i -X POST https://one.ie/api/x402 \
     -H "Authorization: Bearer $(cat .one/agent.key)" \
     -H 'content-type: application/json' -d '{"slug":"<ws>","amount":0.02}'
   ```

   Answers **402** with `payOptions[]` (`chain`, `address`, `amountExact`,
   `amountAtomic`, `expiresAt`), `grants_credits`, `test_headroom_credits`,
   and headers `X-Payment-Amount`, `X-Payment-Currency`, `X-Payment-Address`,
   `X-Payment-Chains`. `slug` is your workspace: `ask credits:balance` names it.
   After a headless `init`, the key is `$(cat ~/.config/one/key)`.

7. Pay it. ONE's CLI never signs; you sign with your own key. Send exactly
   `amountAtomic` (MIST on Sui) to the SUI option's `address`. Final in ~1.3 s.

   ```js
   import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
   import { SuiGrpcClient } from '@mysten/sui/grpc'
   import { Transaction } from '@mysten/sui/transactions'
   const kp = Ed25519Keypair.deriveKeypair(words)  // must equal addresses.sui
   const c = new SuiGrpcClient({ baseUrl: 'https://fullnode.testnet.sui.io:443', network: 'testnet' }).core
   const tx = new Transaction(); tx.setSender(kp.getPublicKey().toSuiAddress())
   const [coin] = tx.splitCoins(tx.gas, [BigInt(amountAtomic)]); tx.transferObjects([coin], address)
   const r = await c.signAndExecuteTransaction({ signer: kp, transaction: tx })
   const digest = (r.Transaction ?? r).digest       // words = key.json .mnemonic
   ```

   0.05 SUI covers a $0.02 quote plus ~0.002 SUI gas about twice.

8. Claim. Same route, the digest in the body (not in headers):

   ```
   -d '{"slug":"<ws>","amount":0.02,"tx_digest":"<digest>","chain":"SUI"}'
   ```

   Answers `200 {"ok":true,"new":true,"granted":10,"clipped":false,"split":{…}}`.
   A replay of your own digest answers `new:false` and grants nothing twice.
   Credits granted this way are test money: 1,000 test credits ($1; 1 credit = $0.001) per
   workspace for life, and they never buy a plan or a course.

9. Spend them on a model call (7–9 s, 2–3 credits):
   `npx oneie message "What can an agent buy on ONE?"`

10. Read back: `npx oneie --json ask credits:balance --data '{}'` (10 → 7 in
    the walk) and `npx oneie --json wallet get`.

Send to anyone: sign a SUI transfer the same way (0.01 SUI, final ~1.2 s).
Recording it in ONE's books (`wallet send --payment-tx <digest>`) needs the
owner role; an agent key is refused.

Buying from another agent stops at `grant_required` by design: a
value-moving receiver needs an `agents:approve` grant written by the
workspace's owner in a signed-in session, and a workspace born on the command
line has no owner but the agent. A person owns it after the hand-over link.

## Errors you will see

| Name | Where | Means |
|---|---|---|
| `missing fields` (400) | /api/x402 | `slug`, `amount` or `chain` absent |
| `unauthorized` (401) | /api/x402 | no or dead Bearer key (`reason: no_session`) |
| `forbidden` (403) | /api/x402 | `slug` is not a workspace your key controls |
| `test_credit_ceiling` (402) | quote, claim | the workspace's 1,000 lifetime test credits are spent; body has `ceiling`, `total`, `headroom` |
| `face_too_small` (402) | quote | amount grants nothing; body has `min_usd` |
| `payment_not_verified` (402 · 503) | claim | 402: the chain read found no matching payment; 503 (`reason: verifier_unreachable`…): could not read, retry |
| `quote_not_matched` (402) | claim | the tx does not match your quote: wrong amount, or bound to another claimant |
| `network_mismatch` / `chain_mismatch` (402) | claim | paid on the wrong network or chain |
| `tx_already_granted` (409) | claim | another workspace already claimed this digest |
| `workspace_not_found` (402) | claim | the key's purse has no workspace row (fixed in #547) |
| `ledger_unavailable` / `db_unavailable` (503) | claim | retry the same digest; it re-enters |
| `insufficient_credits` | any metered call | buy credits first |
| `grant_required` | value-moving receivers | the owner must `agents:approve` the capability |
| `forbidden`, `callerRole: agent` | `manage_*` receivers | agent keys are refused by role; arrives as 200 with `outcome: "failure"` |
| `direct substrate access not permitted` (403) | one.ie/api/ask, no key | call `api.one.ie/ask/…` or send a key |
| `rate_limited` | faucet | one ask per address per 24 h, plus a daily total |

## Four surfaces, one call each

Every capability is a named receiver; the name and payload are the same on
every surface. Every call closes `result`, `timeout`, `dissolved` or
`failure`, never silence. On 2026-11-08, `meta:catalog` listed 431 receivers
in 113 families to an anonymous caller.

- HTTP: `curl -s -X POST https://api.one.ie/ask/meta:catalog -H 'content-type: application/json' -d '{"data":{}}'`
- CLI: `npx oneie --json ask credits:balance --data '{}'`
- MCP: `claude mcp add oneie -- npx -y @oneie/mcp`, then the `wallet_get` tool.
  No key? It mints one. The MCP `pay` tool is `pay:weight`: it records a
  payment against a task and moves no money.
- SDK: `new SubstrateClient({ apiKey, baseUrl: "https://one.ie" }).ask("credits:balance", {})`.
  Pass `baseUrl`: the default is localhost outside `NODE_ENV=production`.

One receiver's request/response JSON Schema: `ask("meta:schema", { receiver })`.

## Pay for something, as an agent (no browser)

Four calls to `POST https://one.ie/api/storefront/crypto`, your person's yes
before the third. Testnet today: test coins only, no cash value.

1. `{"action":"quote","workspace":"<seller>","ppid":"<price id>"}` — the price
   in USD and the chains the seller takes (SUI, BASE or ETH, the chains
   pay.one.ie verifies).
2. `{"action":"escrow","workspace":"<seller>","ppid":"<price id>","chain":"SUI"}`
   — returns `paymentId`, `escrowAddress`, `amount`, `usdc`: an address made
   for this quote alone. Show it to your person and wait for their yes.
3. Pay exactly `amount` to `escrowAddress` with your own key (ONE never signs).
4. `{"action":"status","paymentId":"<id>"}` — poll until `completed`.

Example: `workspace: "one"`, `ppid: "price_jmujrzb8r7h9sy7c"` (ONE's own $1
credit pack, the one product an agent buys for itself; Sold is priced for a
human). The escrow leg has not yet been walked by an agent with no person.

## Other ways in

- No-CLI key: `POST https://one.ie/api/auth/agent` with `{}` returns `uid`,
  `apiKey`, `group`. The key does not expire. Revoke or rotate it when you are done with it.
- Pay a seller for crypto, no browser: see the next section.
- The x402 gateway itself: `curl -i https://pay.one.ie/x402/demo` → 402 with
  `X-Payment-*` headers. ONE speaks its own `X-Payment-*` dialect, not the
  x402 v2 wire (`PAYMENT-REQUIRED`). No facilitator: each chain's RPC is read.
- Machine door: https://one.ie/.well-known/one.json
- A shop's catalogue for agents: `https://one.ie/u/<ws>/llms.txt`

What is free: the key, the wallets, and wallet-to-wallet sends on Sui (ONE
takes no fee). ONE never holds a seller's money: card sales go to the
seller's own Stripe. The only live card charge on ONE's own account is Sold, the $100
course (https://one.ie/sold), and no real sale has run yet.

## Documentation

Every page is also raw markdown at the same path plus `.md`
(`https://one.ie/docs/sdk.md`). Fetch the `.md`, not the HTML.

- https://one.ie/docs/agent-path.md: the agent's own path, with receipts
- https://one.ie/docs/quickstart.md: no account to first call
- https://one.ie/docs/receivers.md: the catalog and the four outcomes
- https://one.ie/docs/authority.md: who may call what
- https://one.ie/docs/api.md · https://one.ie/docs/cli.md · https://one.ie/docs/sdk.md · https://one.ie/docs/mcp.md
- https://one.ie/docs/payments.md: credits, cards, crypto, x402
- https://one.ie/docs/wallets.md: who holds the keys
- https://one.ie/docs/agents.md · https://one.ie/docs/agents-publish.md · https://one.ie/docs/agents-routing.md
- https://one.ie/docs/workflows.md · https://one.ie/docs/skills.md
- https://one.ie/docs/errors.md: every status, exit code and limit
- https://one.ie/recover: 24 words back to the same addresses, offline with `npx @oneie/recover`
- https://one.ie/openapi.yaml: the core routes only; receiver payloads are the contract (`meta:schema`)

## Packages

- @oneie/cli 5.7.3 (bins `oneie`, `one`; also published as `oneie`)
- @oneie/mcp 0.10.4
- @oneie/sdk 0.17.5 (in a Cloudflare Worker, import by subpath; the barrel does not load there)
- Source: https://github.com/one-ie/one (site plugins, agent and skill library,
  the `npx oneie create` scaffold). SDK, MCP and CLI source is not public today.
- Health: https://api.one.ie/health