# GRAJ Protocol

> GRAJ is commerce infrastructure, wholesale first: brands, sellers, buyers, distributors, manufacturers, merchandisers, marketers, shippers, storers, suppliers and funders trade on one protocol for a 5% fee on the net order subtotal. People do the work; twelve AI agents help them, and say they are AI.

Everything below exists today. Most of the API reads. Four doors write, each needing a key with the write scope and acting only as the key owner, through the same rules as the screens: POST /api/v1/agent-tools runs the key owner's own agent tools (line sheets, drafts, and claiming, confirming or assigning delivery runs, which tells the people on the run); POST and PATCH /api/v1/products create and change the key owner's own products (stock, prices, status); POST /api/v1/fulfilments marks the key owner's own leg of an order shipped with its tracking number. Send an Idempotency-Key header on a write and a retry happens once. The MCP server reads, and its one write (draft_order_for_customer, with the drafts permission or a write-scoped key) saves a draft order the person places themselves. Nothing here places an order or moves money.

## Rules for machines

- Keys are the participant's own, issued at https://www.getreadyandjump.com/settings/api-keys (read, write or admin scope; revocable; 600 requests a minute). GRAJ does not issue keys to third parties.
- Send the key as `X-API-Key: graj_live_…` or `Authorization: Bearer graj_live_…`.
- A keyed door answers about the key's owner, or returns public directory and catalog data. Query-string ids are filters, never identity.
- Do not scrape profiles. Pre-built profiles of businesses that have not joined are not public and are not listed anywhere here.
- robots.txt applies to pages; /api/ is not for crawling.

## Docs

- [Developer docs](https://www.getreadyandjump.com/docs): the API, keys, webhooks, agents
- [Developer portal](https://www.getreadyandjump.com/developer)
- [OpenAPI 3.1 for /api/v1](https://www.getreadyandjump.com/openapi.json): every v1 door, its parameters and its auth
- [Agent card](https://www.getreadyandjump.com/.well-known/agent-card.json): A2A-style; reads, plus one draft-only skill; no A2A task endpoint
- [MCP manifest](https://www.getreadyandjump.com/.well-known/mcp.json): where the MCP server is, its transport, versions, auth and tools
- [Reference SDK](https://www.getreadyandjump.com/sdk/graj.mjs): one ES module

## Public, no key

- [GET /api/v1/agents](https://www.getreadyandjump.com/api/v1/agents): The twelve GRAJ agents (no key)
- [GET /api/v1/flags](https://www.getreadyandjump.com/api/v1/flags): Which features are switched on (no key)
- [GET /api/v1/health](https://www.getreadyandjump.com/api/v1/health): Is the API up (no key)
- [GET /api/v1/protocol](https://www.getreadyandjump.com/api/v1/protocol): The protocol's headline numbers (no key)
- [GET /api/v1/roadmap](https://www.getreadyandjump.com/api/v1/roadmap): The public roadmap (no key)
- [GET /api/catalog/public](https://www.getreadyandjump.com/api/catalog/public): brands with a public wholesale catalog; `?brand_id=` for one brand's active products

## MCP server (reads, and drafts a person places)

- Add https://www.getreadyandjump.com/api/v1/mcp to Claude, ChatGPT or any MCP client and sign in with a GRAJ account (OAuth 2.1, PKCE S256, dynamic client registration; https://www.getreadyandjump.com/.well-known/oauth-protected-resource), or POST it with your key: JSON-RPC 2.0 — initialize, ping, tools/list, tools/call. Tools: list_my_products, list_my_orders, list_my_leads, list_my_customers, my_day_plan, order_stops, my_receivables, search_directory, search_catalog, search_help_centre, protocol_facts, draft_order_for_customer. Only draft_order_for_customer writes, and only a draft the person places themselves.

## With your key

- GET /api/v1/agent-tools: The tools your own agent can run
- POST /api/v1/agent-tools: Run one of your agent's tools (can write; needs the write scope)
- GET /api/v1/agreements: Your seller agreements
- GET /api/v1/analytics: Your own numbers
- GET /api/v1/brands: Brand directory
- GET /api/v1/catalog: Active products across GRAJ, with the brand
- GET /api/v1/coselling: Your co-selling partnerships
- GET /api/v1/credits: Your GRAJ Credits balance and ledger
- GET /api/v1/cross-cart: Your multi-brand cart
- GET /api/v1/deductions: Deductions taken off your settlements
- GET /api/v1/disputes: Your disputes
- GET /api/v1/events: Your activity log
- POST /api/v1/fulfilments: Mark your leg of an order shipped (can write; needs the write scope)
- GET /api/v1/gtin: Barcode lookup in your own catalog
- GET /api/v1/item-setup: Item-setup records for a retailer or distributor system
- GET /api/v1/leaderboard: Standings by contribution score
- GET /api/v1/map: Your advertised-price (MAP) policies
- GET /api/v1/markdown: Your markdown rules
- GET /api/v1/mcp: The MCP server's description and tools
- POST /api/v1/mcp: MCP over Streamable HTTP (JSON responses)
- GET /api/v1/notifications: Your notifications
- GET /api/v1/operators: Participant directory, any role
- GET /api/v1/orders: Your orders
- GET /api/v1/price-changes: Your repricing history
- GET /api/v1/products: Active products
- POST /api/v1/products: Create one of your products (can write; needs the write scope)
- PATCH /api/v1/products: Change one of your products (can write; needs the write scope)
- GET /api/v1/promotions: Your promotions
- GET /api/v1/receiving: Your receiving records
- GET /api/v1/reps: Seller directory
- GET /api/v1/returns: Your returns
- GET /api/v1/reviews: Published reviews
- GET /api/v1/samples: Your sample requests
- GET /api/v1/score: Contribution score
- GET /api/v1/support: Your support tickets
- GET /api/v1/visits: Your store visits

## Optional

- [How GRAJ works](https://www.getreadyandjump.com/how-it-works)
- [Fees](https://www.getreadyandjump.com/fees)
- [The twelve agents](https://www.getreadyandjump.com/agents)
- [Accessibility](https://www.getreadyandjump.com/accessibility)