Protocol, SDK, CLI, and reference agents for mandate-enforced agent payments on Stellar. The SDK prepares requests; the contract decides whether money moves.
A user defines the budget and scope. An agent can request payment, but only the MandateRegistry can validate, consume, and transfer against that authorization.
flowchart LR
U["User\nsigns IntentMandate"] --> R["Register mandate\napprove contract allowance"]
R --> C["MandateRegistry\nauthoritative boundary"]
A["Agent"] --> F["agent.fetch()"]
F --> M["Fulfillment API"]
M -->|"authenticated bound-v2 challenge"| F
F --> P["execute_payment"]
P --> C
C --> V["Re-check\nauth · scope · budget\nexpiry · sequence"]
V --> X["Consume mandate\nspent + sequence"]
X --> T["SEP-41 transfer_from"]
T --> M
M -->|"verify request signature + chain evidence"| D["Serve resource"]
D --> A
SDK["SDK / CLI\nuntrusted convenience layer"] -.-> A
SDK -.-> U
style C fill:#1a1a2e,stroke:#7B73FF,color:#fff
style V fill:#16213e,stroke:#00d9a5,color:#fff
style X fill:#16213e,stroke:#00d9a5,color:#fff
style T fill:#16213e,stroke:#e94560,color:#fff
Mainnet invariant: money moves only through
MandateRegistry.execute_payment, which validates and consumes the mandate atomically with its transfer. The user approves the SEP-41 allowance for the contract, never for the agent, SDK, or CLI. Historical composite contracts have their own separately documented payment interface.
| Property | Protocol guarantee |
|---|---|
| Contract-authoritative limits | Budget, merchant scope, asset, expiry, caller authorization, and sequence are re-checked on every payment. |
| Atomic enforcement | Mandate consumption and token transfer happen in one transaction; a failed transfer reverts the state change. |
| SDK cannot bypass policy | The SDK and CLI hold no spending authority. They submit requests to the same contract boundary as any other caller. |
| Replay resistance | Every spend supplies the current mandate sequence; stale and out-of-order calls are rejected. |
| Bound HTTP delivery | Exact-origin GET challenges, agent signatures, pre-broadcast receipts, explicit application acknowledgment, and atomic claim plus immutable-result replay close public-transaction reuse. |
| Adaptable HTTP layer | x402 request and response parsing is isolated from the mandate model and contract interface. |
| Controlled evolution | Mainnet V2 supports native 2-of-3 administration, pause, and authorized same-address implementation upgrades. |
The current Mainnet V2 registry is
CCLZEBJXG4YVJEPBCR5F27N733BCK5HQJWZZGB3K54JVODY3VAGP4HWR.
The coordinated release makes this the default Mainnet target through MAINNET
from @ackrate/stellar@0.3.0, ackrate.mainnet in Core, and the rebuilt CLI.
The complete official manifest is bundled; users do not need to copy the address
or supply a separate manifest file. Source and artifact identity remain pinned
alongside the address.
See the five-package Mainnet configuration map for Stellar 0.3.0, Core 0.4.0, AP2 0.4.0, Express middleware 0.3.0, and CLI 0.2.0, including the exact configuration file and clickable contract explorer links. All five versions are published and independently verified; dated release evidence is below.
import { MAINNET } from "@ackrate/stellar";
import { ackrate } from "@ackrate/core";
console.log(MAINNET.mandateRegistryId);
console.log(ackrate.mainnet.settlementAsset.contractId); // Canonical Mainnet USDC.Mainnet uses real USDC and XLM fees. A default configuration is not permission
to spend: user/agent signatures, budget approval, live-state checks, and the CLI's
real-USDC confirmation guards remain required. The advanced
publishedMainnetNetworkFromDeploymentManifest helper validates a supplied
complete record against this official deployment; it is not required to use the
bundled Mainnet profile. Authorized upgrades replace the implementation at the
same contract address, with compatibility and release-evidence review still required.
V2 administration uses native Stellar 2-of-3 account authorization. Upgrades require administrator authorization and paused state. This V2 deployment has no integrated timelock and does not use the older registry's OpenZeppelin role implementation. The separate older contracts remain documented under their own addresses and profiles. See the Stellar package configuration and signature-coordination commands.
| Surface | Current source or deployment |
|---|---|
| Mainnet V2 MandateRegistry | CCLZEBJX…4HWR — the official default registry, native 2-of-3 administration, and same-address upgrades |
| Hosted wallet workflow | Wallet demo project — user-signed setup, mandate-validated payments, and service results |
| Contract releases and hashes | ackrate-protocol-contracts |
| High-level SDK | @ackrate/core — mandates, payments, and agent.fetch() |
| Stellar binding | @ackrate/stellar — typed contract client, network config, signers, and SEP-41 helpers |
| AP2 profile | @ackrate/ap2 — signed, version-pinned AP2 v0.1 validation plus fail-closed binding into the contract mandate |
| Express middleware | @ackrate/express-middleware — authenticated bound-v2 challenges, independent settlement verification, and a paid JSON route with atomic claim plus immutable-result replay |
| CLI | @ackrate/cli — setup, mandate creation, crash-safe payment reconciliation, exact success acknowledgment, and demo flow |
Package releases and protocol/specification versions are separate axes.
All five coordinated Mainnet-default releases are published. Registry checks
on 2026-09-07 at 04:25:38–04:25:45 Bangkok (UTC+7) matched each latest tag
and downloaded archive's SHA-512 to the verified release bytes. A fresh public
installation passed strict TypeScript, ESM, default-contract/full-V2-interface,
package-README, and CLI guard checks at 04:25:11, with zero dependency findings.
See the Step 1 release evidence.
| Package | Current public version | Earlier 03:33 checkpoint | Protocol/specification target |
|---|---|---|---|
@ackrate/stellar |
0.3.0 |
0.2.5 |
Built-in official MAINNET, complete manifest, and contract access |
@ackrate/core |
0.4.0 |
0.3.4 |
Mainnet-default mandates, payments, and delivery recovery |
@ackrate/ap2 |
0.4.0 |
0.3.2 |
AP2 0.1.0 profile bridged into the Mainnet Core flow |
@ackrate/express-middleware |
0.3.0 |
0.2.4 |
Mainnet USDC bound-v2 proof verification and durable delivery |
@ackrate/cli |
0.2.0 |
0.1.9 |
Mainnet-default ackrate command with the official manifest bundled |
The coordinated set requires Node.js 22 or newer and uses the exact
@stellar/stellar-sdk@16.3.0 dependency. AP2 0.4.0 still implements
the AP2 0.1.0 profile; the package version is not the specification version.
The release source is
d0aee212;
GitHub CI 34060795268
was confirmed successful at 04:27 Bangkok. See the
package release matrix for installation commands.
These technical release checks do not claim completion or grant acceptance of
all T3 steps; Step 1 is under user review and Steps 2–4 remain paused.
The contract is authoritative. SDK-side checks only fail fast; they never replace on-chain validation.
| Path | Purpose |
|---|---|
packages/sdk |
@ackrate/core: contract client, bound-v2 adapter, durable settlement receipts, and no-second-payment recovery |
packages/stellar |
@ackrate/stellar: generated binding, network config, signer, and token helpers |
packages/ap2 |
@ackrate/ap2: signed AP2 v0.1 Ackrate profile validator with deterministic binding evidence and 59 tests |
packages/express-middleware |
@ackrate/express-middleware: exact-origin GET verification and at-most-once paid JSON fulfillment |
packages/cli |
@ackrate/cli: terminal workflow, pre-broadcast journal, exact-hash reconciliation, and explicit success acknowledgment |
apps/consumer-agent |
Reference ResearchAgent that buys data through agent.fetch() |
apps/fulfillment-agent |
Reference 402-gated API that verifies settlement before serving |
apps/wallet-chat |
Next.js + LOBSTR wallet flow and mandate-aware AI consumer chat |
scripts |
Testnet demos, live flows, deployment, and gate check tooling |
security |
Threat model, data flows, upgrade custody, and contract/SDK/x402 gate check records |
Use Node.js 22+. Build and verify the release source from this checkout:
npm ci
npm run gatecheck:releaseThe source Mainnet workflow needs existing funded actors and named secure signers. Replace the example identities and merchant address before running; the fully configured command spends real USDC:
npm run cli:bundle
node packages/cli/dist/ackrate-cli.bundle.mjs demo research-agent \
--network mainnet \
--user-signer ackrate-user --agent-signer ackrate-agent \
--agent-secret-env ACKRATE_AGENT_SECRET \
--merchant G... --price 0.01 --budget 0.03 --confirm-real-usdcThe flag --agent-secret-env names an environment variable injected by a secret
manager; never substitute the secret value into the command. The official
Mainnet manifest is bundled. No manual manifest file is needed for this registry.
For the published CLI, use
npx --yes @ackrate/cli@0.2.0 in place of the local bundle command, retaining the
same signer, merchant, price, budget, and confirmation options.
The command starts both reference agents and delivers three resources through HTTP 402, on-chain payment, independent proof verification, and HTTP 200. The contract must reject purchase four without payment. Follow the full CLI prerequisites and recovery instructions. A new Mainnet reference-agent delivery run remains separate from historical direct-payment receipts, local tests, or the hosted marketplace's human test.
Existing development deployments and evidence are retained separately from the official Mainnet default:
To explicitly run the funded development-network reference flow:
npm run agents:testnetThat command creates and funds fresh testnet actors, starts the Express
fulfillment agent, and drives the consumer through real agent.fetch()
purchases. Three resources settle and are independently verified; the fourth is
rejected by the contract-enforced budget. The run also proves exact bound-v2
receipts and rejects an old settlement re-signed for a fresh request. No local
key or environment file is required.
Run the three named SDK failure drills separately:
npm run drills:testnetUse the public browser companion at ackrate.live/express, or follow the verified clean VS Code project guide. Operational evidence and boundaries are in the live drill record, threat model, data flow, and upgrade authority runbook.
The SDK is untrusted. The contract enforces the limit.