Examples & SDK

Copy-paste flows for turning merchant onboarding and agent policy into executable commerce: discovery, direct payments, swap-before-pay, facilitator/x402 policy, receipts, disputes, analytics, and reputation.

What These Examples Cover

Registering merchants, services, agents, and payment policies.
Discovering services and preparing a quote-bound purchase.
Checking policy before spending and recording payment evidence.
Recording receipts, fulfillment, disputes, and reputation signals.

Environment

export API_URL=https://cortex-api.projectaegis.ai
export RPC_URL=https://sepolia.base.org
export COMMERCE_REGISTRY_ADDRESS=0xc4c014d9eb2d07ff6f7d2b8625e8cf3bc1150574
export POLICY_MODULE_ADDRESS=0x7120d45cbd6b5d079f39418e4f84880c634ef614
export INTENT_BOOK_ADDRESS=0x16f7e7c4856bad4dcbE61400630087Dab75B229E

Runnable dry-run template

Use ops/sdk-examples/commerce-flow.ts through the demo package to test the SDK flow without sending transactions by default.

cd ops/demo
npm install
npm run sdk:commerce
npm run sdk:payment-rails

Hosted payment rail dry run

ops/sdk-examples/payment-rails.ts consumes hosted catalog and quote URLs, verifies their hashes, computes the quote hash, checks reputation, and prints a rail-specific execution plan before any transaction is sent.

export CATALOG_URL=https://cortex-api.projectaegis.ai/catalogs/0x...
export QUOTE_REQUEST_URL=https://cortex-api.projectaegis.ai/quote-requests/0x...
export QUOTE_RESPONSE_URL=https://cortex-api.projectaegis.ai/quote-responses/0x...
npm run sdk:payment-rails

Current Base Sepolia contract semantics are rail-aware: facilitator and x402 quotes require an active facilitator, while transfer and swap quotes can use address(0) and allow the merchant or agent to record the receipt.

Client Setup

const cortex = new AgentChainClient({
  apiUrl: process.env.API_URL ?? "https://cortex-api.projectaegis.ai",
  publicClient,
  walletClient,
  chain: baseSepolia,
  intentBookAddress: process.env.INTENT_BOOK_ADDRESS as `0x${string}`,
  commerceRegistryAddress: process.env.COMMERCE_REGISTRY_ADDRESS as `0x${string}`,
  policyModuleAddress: process.env.POLICY_MODULE_ADDRESS as `0x${string}`,
});

Quote and Direct Transfer

Compute the quote hash, commit it onchain, then pay through a normal ERC-20 transfer.

const quoteHash = await cortex.computeQuoteHash(quote);
await cortex.commitQuote(quote);

await walletClient.writeContract({
  address: quote.token,
  abi: ERC20ABI,
  functionName: "transfer",
  args: [merchantPayoutAddress, quote.amount],
});

Facilitator and x402 Policy

Configure signed payment budgets and record the exact x402 payload hash against policy.

await cortex.setPaymentPolicy({
  merchant: merchantOwnerAddress,
  token: usdcAddress,
  facilitator: facilitatorAddress,
  maxPerPayment: 1_000_000n,
  maxPerDay: 10_000_000n,
  allowed: true,
});

const x402PayloadHash = keccak256(stringToHex(normalizedX402Payload));
await cortex.recordSignedPayment(
  merchantOwnerAddress,
  usdcAddress,
  facilitatorAddress,
  1_000_000n,
  x402PayloadHash,
);

Receipts and Disputes

const receiptTx = await cortex.recordReceipt(quoteHash, resultHash);
const receipts = await cortex.listReceipts({ agent: account.address, merchant_id: 1n });

const disputeTx = await cortex.openDispute(receiptId, reasonHash);
await cortex.resolveDispute(disputeId, 1, resolutionHash);

Full Examples

The full markdown includes direct stablecoin transfer, swap-before-pay, x402 quote binding, receipt/fulfillment, dispute, analytics, and reputation examples.

View full markdown