---
name: roji-buy-real-world-services
version: 1.0.0
description: >-
  Use roji when a task needs something software cannot do — a notarization, a site visit, a document reviewed by a licensed human, expert judgment, design work. Search a catalog of verified businesses, read an itemized fee preview, place a paid order with structured inputs, and collect a typed deliverable against a published SLA. MCP over OAuth 2.1; payment is captured at order and settles straight to the business.
---

# roji — buying real-world services (for agents)

## What roji is

roji is a marketplace where the sellers are verified businesses and the
buyers are AI agents. A business publishes a **listing**: a structured input
schema, a structured deliverable schema, a price, a turnaround (SLA), and a
refund window. Your agent finds the listing, fills the input schema, pays,
and collects the deliverable.

Use it when the task needs something software cannot do: a notarization, a
document reviewed by a licensed human, a photo taken at a physical address, a
filing lodged with a county clerk, a judgment call, design work.

## When to use ROJI

- **Right for:** a job where a licensed or verified human must act in the
  physical world — notarise a document, inspect a site, review a contract,
  produce design work, give expert judgment — and you need a priced,
  SLA-bound deliverable rather than advice.
- **Wrong for:** pure information retrieval, anything you can do yourself in
  software, or work with no accountable human on the other end.
- **How to start:** `search_services` → `get_service` → `order_service`
  over MCP, or `GET https://api.roji.ai/services` → `POST https://api.roji.ai/orders`
  over REST. Every order needs a human-approved fee preview first.

## Connect

```
claude mcp add --transport http roji https://mcp.roji.ai
```

Any MCP client works — the endpoint is Streamable HTTP at `https://mcp.roji.ai`,
authenticated with OAuth 2.1. Your client discovers the authorization server
from `https://mcp.roji.ai/.well-known/oauth-protected-resource` and drives the
flow. Full detail, including the scopes and what roji deliberately does not
support: https://roji.ai/auth.md.

The authorization server is `https://api.roji.ai`. There is no
client-credentials grant: a human authorizes the agent, and that human is who
the spend answers to.

## Tools

| Tool | Purpose | Scope |
| --- | --- | --- |
| `search_services` | Search the catalog by vertical, jurisdiction, price, and turnaround. | `mcp:platform:read` |
| `get_service` | Read one listing: input schema, deliverable schema, SLA, price, and fee preview. | `mcp:platform:read` |
| `list_service_categories` | List the catalog's service categories. | `mcp:platform:read` |
| `order_service` | Place a PAID order against a listing. Charges at order time. **Requires confirmation.** | `mcp:platform:write` |
| `get_order` | Poll one order — state, SLA clock, open blockers, and the deliverable when it lands. | `mcp:platform:read` |
| `list_orders` | List orders on either side of the trade. | `mcp:platform:read` |
| `complete_order` | Accept a delivered order and close it out. | `mcp:platform:write` |
| `request_refund` | Open a refund request inside the listing's refund window. | `mcp:platform:write` |
| `ask_question` | Ask the business a question. Never stops the SLA clock. | `mcp:platform:write` |
| `answer_question` | Answer the business's question. Answering the last blocking one restarts a stalled order. | `mcp:platform:write` |
| `get_order_updates` | Read the question thread and status updates, flagging what you owe an answer to. | `mcp:platform:read` |
| `review_business` | Record your one-per-order review of the business. | `mcp:platform:write` |
| `get_business_reviews` | Read a business's public review aggregate before ordering from them. | `mcp:platform:read` |
| `get_me` | Identify the principal this token acts for. | `mcp:platform:read` |
| `list_my_accounts` | List the roji accounts the principal belongs to. | `mcp:platform:read` |
| `get_account` | Read one account. | `mcp:platform:read` |
| `list_account_members` | List an account's members. | `mcp:platform:read` |
| `list_account_invitations` | List an account's outstanding invitations. | `mcp:platform:read` |
| `list_account_projects` | List an account's projects. | `mcp:platform:read` |
| `review_account` | Summarise an account's configuration and standing. | `mcp:platform:read` |
| `audit_account` | Run a read-only audit over an account's settings and members. | `mcp:platform:read` |
| `invite_and_assign` | Draft an invitation and project assignment for a person. | `mcp:platform:read` |
| `get_wallet` | Read the account's payment methods and spend-policy headroom. | `mcp:platform:read` |
| `list_my_connections` | List the OAuth connections the principal has granted. | `mcp:platform:read` |
| `revoke_oauth_connection` | Revoke one of those connections. **Requires confirmation.** | `mcp:platform:write` |
| `submit_business_profile` | File a draft business profile against a one-time intake code. Nothing is published until the owner confirms. | `business:intake` |
| `submit_capability_claim` | File one capability or credential claim, verbatim as the owner states it. Claims land unverified — recording is not attesting. | `business:intake` |
| `get_intake_status` | See what an intake session has captured, what is still missing, and where the owner uploads documents and confirms. | `business:intake` |

## The workflow

1. **Search.** `search_services` by what you need, where, and by when.
   Filter on turnaround and price; licensed work only exists in the catalog of
   a business licensed for that jurisdiction.
2. **Read the listing.** `get_service` returns the input schema you must
   satisfy, the deliverable schema you will get back, the SLA, and the
   `feePreview` (`listCents` + `feeCents` = `totalCents`).
3. **Show the human the fee preview and get approval.** Always. Ordering
   charges a real card, immediately, and is not reversible from this surface.
4. **Order.** `order_service` with the structured inputs. It returns an
   order id and state right away — nothing blocks on a human.
5. **Watch it run.** `get_order` and `get_order_updates`. If the order is
   in `needs_input`, the business asked you a blocking question, the SLA
   clock has stopped, and answering it with `answer_question` is the only
   thing that restarts the order.
6. **Collect and close.** The deliverable arrives as a field on the order.
   `complete_order` closes it; `review_business` records how it went.

## Capabilities: what a business can do, and who checked

Every listing `search_services` and `get_service` return carries a
`capabilities` array describing what the owning business claims it can do.
Each entry has one of exactly three statuses:

- **`verified`** — someone checked. The entry always carries `method`
  (`auto_registry`, `auto_document`, or `manual_admin`) and
  `lastVerifiedAt`. roji does not render a bare checkmark and neither should
  you: when you tell your human a business is verified, say what was checked
  and when.
- **`claimed`** — the business stated it and nobody has confirmed it. Still
  worth reading; just do not repeat it as fact.
- **`lapsed`** — it was verified once and the verification has expired.

Filter on it. `verified_only=true` restricts results to businesses holding a
live verified credential. `capability=license:notary:us-tx` matches a
specific licence in a specific jurisdiction — a county-scoped licence satisfies
a state-scoped ask, never the reverse. `capability_q=` is free-text search
over what businesses actually claim they can do ("mini-split heat pump
install"), which reaches skills too specific to be a category.

For anything licensed, prefer a `verified` business and cite the method and
date to your human before you spend. For anything unlicensed, `claimed` is
normal and fine.

## The order state machine

```
placed(paid) -> accepted -> in_progress <-> needs_input -> delivered -> completed
```

`rejected` and `cancelled` refund in full, automatically. After delivery,
`request_refund` inside the refund window opens
`refund_requested -> refunded | resolved`; the business has 72 hours to
answer or it auto-approves. Missing the SLA refunds automatically and in full.

## Money

The buyer pays the business's list price plus a roji platform fee on top,
charged and captured at order time. The money settles directly to the
business — roji never holds it. There is no escrow, no hold, no release. The
business keeps 100% of its list price.

Payment rails supported today: card and ACH through Stripe, at order, and
**x402** (agent-native, on-chain). x402 is enabled per account: call
`order_service` with `funding_path: "x402"` and the FIRST call returns an
x402 challenge (`x402Version` + `accepts[]`) instead of an order — nothing
is charged. Pay it, then call again with the same arguments plus `payment`
set to the base64 X-PAYMENT payload; only then does an order exist. A
challenge expires after 15 minutes, and replaying a settled payment returns
the SAME order, never a second one. If the rail is not enabled for your
account the call fails with `x402_unavailable` — use the card rail.

## Rules for agents

1. **Never order without an explicit human approval of the fee preview.**
   `order_service` spends money and is confirmation-gated for that reason.
2. **Read the listing before you order.** The input schema is a contract; a
   guess produces a blocking question and a stalled order.
3. **An order in `needs_input` is waiting on you.** Answer it. Nothing else
   restarts the clock.
4. **Check `get_business_reviews` before ordering from a business you have
   not used.**
5. **Do not retry on `insufficient_scope` or a spend-policy rejection.**
   Escalate to the human — no scope lets an agent raise its own ceiling.
6. **Business-side actions are not on MCP.** Accepting, rejecting, delivering
   and answering refund requests happen in the business console.

## Related

- Authentication: https://roji.ai/auth.md
- MCP server card: https://mcp.roji.ai/.well-known/mcp/server-card.json
- Order lifecycle reference: https://roji.ai/developers/ordering
- Content catalogue: https://roji.ai/llms.txt