Agentic Economy

Revised: 2026-10-05

Agentic Economy helps Australian businesses connect their agents to paid tools and services through one account, with AUD credit, spending controls, clear usage and billing records, and recovery when something goes wrong. x402 services are the first supported supply.

An agent stays in its existing app or framework. It finds a service when needed, checks the price and terms, and makes a Call within its spending policy. AE does not own the agent's larger project, planning, memory or orchestration.

Read PRODUCT.md for the active direction, CONTEXT.md for familiar product terms, source contracts and compatibility names, and the Australian whitepaper for the institutional thesis. New to the vocabulary? Start with the glossary. Use the documentation index for current work, maintained contracts, operations and historical evidence.

The product loop

find and compare Tools -> Quote and spending checks -> Call
    -> result or pending outcome -> recovery or refund if required
    -> resolved purchase -> agent continues

A Quote binds the customer, agent, spending policy, exact Tool version, Provider, Seller, inputs, price ceiling, terms, data use, effects and retry rule before a paid Call. Calls with uncertain delivery or payment remain open for recovery; a successful payment alone does not establish delivery.

For supported resale purchases, AE is the buyer-facing Seller. The Provider performs the service, and the amount AE owes the Provider is recorded separately from the customer's charge. AUD customer credit is not a crypto wallet.

One shared account balance can serve several agents under separate hard limits. Authentication resolves the account. The accepted source machine path is registry.tools.search -> tool.quote -> tool.call -> result. Status and recovery appear only when needed. Public detail, comparison, whoami and balance are optional reads. Agents do not coordinate treasury, calculate foreign exchange, write ledger entries or guess whether payment can be retried.

The production application and backend are deployed. The authenticated CLI has completed the recorded 20-payment mainnet acceptance. The public npm package @agentic-economy/cli is published at 0.2.1. The separate paid development chat journey remains open; see the deployment map.

Current stage

For current application hosts, staging, retired test projects and remaining production blockers, use the deployment map. The production execution queue is Wayfinder #256.

The implemented foundation includes canonical Tools, comparison, Quotes, brokered Calls, prepaid buyer credit, Charges, Provider earnings, refunds, status and recovery.

Owner reporting includes scoped Call totals, monthly Agent usage and charge coverage, sortable history and exports. Receipts include generation of approved funding tax invoices and linked full-refund adjustment notes, with immutable HTML/print and CSV records. Treasury shows the six commercial approval families and proposed defaults through its existing protected review flow. The readiness record distinguishes verified production payments and recovery from controlled failure fixtures and remaining availability limits. Screening is explicitly deferred under the approved alpha policy.

The complete Australian principal-reseller record is the next product milestone. Buyer-facing Seller identity, a separate Provider obligation, attributed tax facts, business-document evidence and purchase resolution are not yet one explicit production record. Source and tests remain the authority for current behaviour.

Usage metering and the founder console now share the main delivery stream. Historical backfill, automatic reporting schedules and external metering remain explicit opt-in operations; implementation does not activate them.

Current source entrances

• /market exposes the public service catalogue and comparison flow.
• /t/new provides a thin natural-language entrance to the same market.
• /api/v1/market-tools/* exposes canonical Tool discovery and comparison.
• /api/v1/tools/quote and /api/v1/tools/call define paid or consequential Calls.
• /api/v1/calls and /api/v1/calls/{callRef}/* define Call history and recovery.
• /api/v1/feedback, MCP ae_feedback_submit and CLI ae feedback accept optional product feedback through the existing PostHog project. See feedback and opt-out.
• /mcp, /llms.txt and /SKILL.md are the accepted source discovery/plugin surfaces. The deployment map identifies their current hosted release.
• The CLI source supports search, describe, call, history, status, wait, cancel and recover. The npm package is @agentic-economy/cli, with ae as its command. See CLI installation for versioned npm installation and verified signed archives; a registry 404 means the selected npm version has not been published yet.
• /for-providers admits and publishes Provider Tools in source.

Chat is a thin entrance to the same Tool market and controlled purchase plane. The recorded paid production acceptance used the CLI; paid chat completion is a separate journey and remains unverified.

The external registry discovers possible supply at metadata authority only. An imported record is not a Tool and cannot be called until Agentic Economy admits and publishes it.

Documentation authority

• PRODUCT.md defines the active product and commercial direction.
• AGENTIC_ECONOMY_AUSTRALIA_WHITEPAPER.md explains why the institution should exist.
• CONTEXT.md defines the shared language.
• START_LINE.md defines the complete managed-Call commercial proof.
• IMPLEMENTATION_ROADMAP.md defines the delivery sequence to the mature platform.
• Agent operating contract defines the coherent machine-facing control loop.
• DESIGN.md defines how the product communicates those facts.
• Current source and tests define what is implemented.

Dated research, comparison papers, gauntlets and working ledgers inform the product but do not override these documents.

The manifesto and investment thesis are supporting strategy. Browser test profiles live under tests/config/; playwright.config.ts remains the default local entry point. Use npm run test:e2e:authenticated or npm run smoke:chat:staging for the specialist profiles and their required environments. E2e/a11y Playwright specs are shell and accessibility checks, not product proof.

Publish an x402 Tool

Start at /for-providers and follow the source preview and returned status for the selected endpoint.

An x402 payee is a payment recipient. The wallet address does not, by itself, establish the commercial Seller or Provider.

Run locally

Use Node.js 22 and npm 11.5.1.

nvm install
nvm use
npm install --global [email protected] --ignore-scripts
npm ci
npm run dev:local

.nvmrc, package.json and convex.json select Node 22; CI uses the same Node major and npm version. With NVM's project auto-switching enabled, entering this checkout selects Node 22 without changing other projects' defaults. For an agent shell that does not load NVM, use its supplied runner from the project directory: NODE_VERSION=22 "$HOME/.nvm/nvm-exec" npm run check:convex-codegen. Restart existing terminals or select Node 22 explicitly after changing shell setup.

Open http://127.0.0.1:3024/market for the catalogue or http://127.0.0.1:3024/t/new for chat.

npm run dev:local starts the local Convex deployment, verifies its URL, and starts Vite with real Clerk identity. It explicitly sets AE_DEPLOYMENT_ENVIRONMENT=development in both runtimes. Hosted Vercel and Convex deployments must each declare the same development or production value; missing or mismatched declarations refuse new money operations. Once Vite is ready, it independently starts optional owner-authority seeding, directory scan kickoff (unless a complete catalogue generation exists), sandbox Tool publication, and FX refresh; failure of one optional stage does not stop the app. ae doctor reports diagnostics without stopping the stack. Use --no-doctor to omit it. It mounts the real ClerkProvider, so CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY and AE_E2E_OWNER_EMAIL must be present. A large local database slows the backend's start; CONVEX_LOCAL_BACKEND_STARTUP_TIMEOUT_SECS (default 300) bounds the wait.

To bind a buyer credential, after startup run npm run connect:local -- --base-url http://127.0.0.1:3024. It runs ae connect and prints the approval URL and user code; approve in the browser as the owner. Consent approval requires Clerk's strict reverification, so there is no headless approval path anywhere. Use --provider to bind a provider credential the same way.

In each Clerk instance, add {"reverification_id":"{{session.reverification_id}}"} to the customized session token claims, following Clerk's action correlation guide. Operator commands, spending-limit increases, workspace closure/ownership transfer and owner-chat approvals require fresh verification of both factors. The web server signs the verified session evidence for Convex; adding fva to a Convex JWT template cannot establish this check. Spending reductions need no MFA prompt.

For a Clerk development instance only, use a dedicated test owner for inbox-free local consent: create a Clerk user with an address such as [email protected], set AE_E2E_OWNER_EMAIL to that same address before starting dev:local (so the seeded Convex owner matches), and sign in as that user. In Clerk's development test mode, request the email verification code normally and enter 424242; no test email is delivered. If strict reverification requests a second factor, enroll SMS MFA on the test owner using a fictional test number such as +12015550100; request its SMS code and enter 424242, or enroll TOTP and use the authenticator's current code. Complete the browser reverification prompt on the consent page, then approve. The email test code alone is not an MFA bypass and a real owner's email cannot use it. Keep production MFA and the server's strict proof check enabled. See Clerk test emails and phones and Clerk MFA.

Then npm run ae -- doctor --json --base-url http://127.0.0.1:3024 shows three groups: discovery, quoting, purchase. On a loopback origin the doctor reports quoting skipped: the seeded sandbox Tool is only listed where the readiness probe can reach it, which is a public HTTPS origin (a preview or hosted deployment). Locally you can prove Discover, connect and the funding diagnostics; Quote and Call are proven on a hosted origin with credentials (tier 1).

Note: npm run dev starts Vite only and is not a valid start path.

Stripe production setup

Use one Stripe live-mode account for credit purchases and Provider payouts. Set STRIPE_SECRET_KEY, STRIPE_READBACK_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_V2_WEBHOOK_SECRET, and STRIPE_AU_INCLUSIVE_GST_TAX_RATE_ID. The API keys must be restricted and the Tax Rate must be active, inclusive, Australian, and exactly 10%; AE verifies that evidence before returning a hosted Checkout link. Production readiness rejects test-mode or malformed values.

Register this event destination:

https://<your-agentic-economy-deployment>/api/stripe/webhook

Subscribe it to checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired, account.updated and the v2.core.account.* lifecycle and recipient-capability events emitted by the Connect setup. The endpoint verifies Stripe's signature over the raw body and applies events idempotently. Do not put secret or webhook keys in browser configuration.

The docs application keeps a separate lockfile. Install its locked dependencies before running the full release gate from a fresh checkout:

npm ci --prefix packages/docs --ignore-scripts
AE_DEPLOYMENT_ENVIRONMENT=development AE_FORMANCE_ENVIRONMENT=sandbox npm run gate

Other useful checks:

npm run test:chat:conformance
npm run test:cli-package

Machine quickstart

The following documents the accepted source CLI contract. It is not a hosted deployment, plugin-installation, or installed-package acceptance claim. The packaged guide remains packages/cli/README.md.

When running locally, include --base-url http://127.0.0.1:3024 with each command; without it, the CLI defaults to the hosted AE origin.

npm run -s ae -- manifest --base-url http://127.0.0.1:3024
npm run -s ae -- search "weather forecast" --limit 5 --base-url http://127.0.0.1:3024
npm run -s ae -- describe <toolRef> --base-url http://127.0.0.1:3024
npm run -s ae -- call <toolRef> --input '{"city":"Perth"}' --base-url http://127.0.0.1:3024

A Plan groups up to ten admitted Tools into a dependency graph. Quote the JSON file, review its exact AUD micro-unit maximum, then run the returned PlanRef with that unchanged total and a stable idempotency key:

npm run -s ae -- plan quote plan.json --base-url http://127.0.0.1:3024 --json
npm run -s ae -- plan run <planRef> <approvedTotalAudUnits> --idempotency-key <key> --base-url http://127.0.0.1:3024 --json
npm run -s ae -- plan resume <recoveryRef> --base-url http://127.0.0.1:3024 --json
npm run -s ae -- plan watch <planRef> --base-url http://127.0.0.1:3024 --json
npm run -s ae -- plan cancel <planRef> --base-url http://127.0.0.1:3024 --json

Approval-required Plans wait for their owner in /plans/<planRef> before any Hold. Cancellation stops future nodes; admitted Calls retain their outcomes and receipts. Read or replay the same Plan after a lost response. Supported paid execution uses admitted managed x402 Tools; paid fixed-AUD execution and unbounded dependent prices refuse before a Hold.

Against a different explicitly verified origin, pass --base-url "$AE_ORIGIN" instead. Do not treat an origin, archive, /mcp, /llms.txt or /SKILL.md read as hosted-release proof.

Project documents

Use PRODUCT.md for product direction, CONTEXT.md for language and IMPLEMENTATION_ROADMAP.md for delivery. TODOS.md is the concise admin/follow-up queue. Dated studies are in research. The documentation index lists the retained records. Earlier planning snapshots do not define a parallel active roadmap.

Share a Git checkout or an export of a reviewed commit, rather than a copy of the working directory. Ignored environment files, local databases, credentials and operator outputs are not part of the repository. Research documents identify local-only or historical citations explicitly; those records are not prerequisites for building the source. Public deployment and installed-client acceptance remain separate from sharing this source.