Ailabra Agent Profit SDK and CLI

Find out whether your AI agent is actually making money. Wallet balance is not profit: Ailabra separates revenue, operating costs, refunds, fees, capital, withdrawals, and transfers, then returns deterministic profit and cash flow. Available through MCP, npm, OpenAPI, and x402.

@jsjfin/agent-profit is the independent public TypeScript SDK and guarded x402 CLI. SDK version 0.1.x supports service major version 1.x; SDK and service versions are intentionally independent.

npm install @jsjfin/agent-profit

No payment is authorized unless the caller explicitly enables payment.

The package exposes the independent typed ProfitApiClient, economic-event and result types, public OpenAPI validation, guarded x402 buyer flow, cumulative budgets, and Ed25519 report verification. It contains no seller implementation, database code, signing private keys, deployment configuration, or production credentials.

Read-only SDK usage

The first call is deliberately non-paying:

import { AgentProfitClient, createEconomicEvent } from "@jsjfin/agent-profit";

const client = new AgentProfitClient({ baseUrl: "https://x402.ailabra.org" });
const discovery = await client.discover();
const event = createEconomicEvent({
  schemaVersion: "1",
  externalId: "invoice_123",
  occurredAt: "2026-07-29T12:00:00Z",
  kind: "revenue",
  direction: "inflow",
  amount: "12.50",
  currency: "USDC",
  category: "customer_revenue",
  source: { name: "my_agent_ledger", type: "manual", verification: "self_reported" },
});
console.log(discovery.paymentInfo, event);

Named profiles prevent URL/network mismatches:

const testClient = AgentProfitClient.fromProfile("testnet");
const mainnetClient = AgentProfitClient.fromProfile("mainnet");

custom requires both baseUrl and expectedNetwork. A named profile only becomes payment-capable when a recipient, limits, and signer are explicitly supplied.

Explicitly payment-enabled SDK usage

Payment requires a caller-owned signer, an explicit network policy, explicit limits, and { pay: true }. The Base-mainnet policy keeps the display symbol USDC separate from the token's EIP-712 name USD Coin.

import { AgentProfitClient, paymentPolicies } from "@jsjfin/agent-profit";
import { privateKeyToAccount } from "viem/accounts";

const client = new AgentProfitClient({
  baseUrl: "https://x402.ailabra.org",
  signer: privateKeyToAccount(process.env.X402_BUYER_PRIVATE_KEY as `0x${string}`),
  paymentPolicy: paymentPolicies.baseMainnetUsdc({
    expectedPayTo: "0x2d6Cee86466807De531a9D3010f06f53b060ab84",
    maxPayment: "0.01",
    maxTotalSpend: "0.01",
    maxAttempts: 1,
  }),
});

await client.calculate({ events: [event] }, { pay: true });

The client validates origin, scheme, network, contract, symbol, decimals, EIP-712 name and version, recipient, per-payment amount, cumulative amount, and attempt count. It rejects redirects and never automatically retries a failed payment. Hardware and external signers work only when they provide a viem-compatible local account interface; browser-wallet prompting is not implemented by this CLI.

Public prices may be bare decimals or strings such as 0.05 USDC. The central parser rejects other assets, negatives, and scientific notation before Decimal arithmetic or signing.

Ailabra Profit Loop

Use the Ailabra Profit Loop to record revenue and attributable costs, keep capital and transfers out of operating profit, compare experiments, and calculate after each meaningful batch. The synthetic three-event example is in examples/profit-loop-events.json.

x402 and LLM event adapters

economicEvents.fromX402Purchase, economicEvents.fromX402Sale, and economicEvents.fromLlmUsage map safe caller-supplied receipts into economic events. A transaction hash alone remains receipt_supplied; callers must set onchainVerified: true only after successful trusted-RPC verification. See examples/x402-event-adapters.ts.

An independent black-box proof that an autonomous agent can keep a local economic ledger, discover Ailabra's public OpenAPI contract, safely purchase a deterministic calculation over x402, verify a signed Ed25519 attestation, and create a self-contained HTML report.

Synthetic demonstration only. The Autonomous Research Brief Service, its customers, revenue, and costs are fictional. Wallet balance is not profit.

What this proves

The CLI uses only public interfaces at https://x402.ailabra.org or the Base Sepolia deployment at https://test-x402.ailabra.org. It does not import Ailabra source or types, access its database, use seller credentials, reproduce its calculation formulas, or bypass payment. Requests and responses are validated against the OpenAPI document fetched at runtime.

synthetic business → local JSON ledger → guarded x402 buyer
  → public OpenAPI validation → deterministic response
  → optional signed attestation → independent Ed25519 verification
  → offline HTML report

Prerequisites and wallet setup

• Node.js 20 or newer (CI uses Node.js 22)
• A separate EVM buyer wallet funded with Base Sepolia ETH and native Base Sepolia USDC
• Never use the seller wallet key, a recovery phrase, or a production treasury key

The buyer follows the official x402 Foundation pattern using @x402/core, @x402/evm, and @x402/fetch. The private key is read only from X402_BUYER_PRIVATE_KEY; it is never written to the ledger, artifacts, terminal output, or logs.

cp .env.example .env
npm ci

For the test deployment:

PROFIT_API_BASE_URL=https://test-x402.ailabra.org
X402_EXPECTED_NETWORK=eip155:84532
X402_EXPECTED_ASSET=0x036cbd53842c5426634e7929541ec2318f3dcf7e
X402_MAX_PAYMENT=0.25
X402_MAX_TOTAL_SPEND=0.31
X402_EXPECTED_PAY_TO=0x... # optional public seller allowlist
X402_BUYER_PRIVATE_KEY=0x... # ignored local environment only

Run the demonstration

npm start -- scenario create
npm start -- ledger list
npm start -- ledger validate
npm start -- calculate
npm start -- analyze
npm start -- attest
npm start -- report

Or run the complete sequence:

npm start -- run-demo
npm start -- run-demo --json
npm start -- run-demo --dry-run

Each paid operation enforces the configured origin, x402 version, exact scheme, network, native-USDC contract, atomic amount ceiling, and optional recipient allowlist before signing. Cross-origin redirects are rejected. X402_MAX_PAYMENT is the per-request ceiling; X402_MAX_TOTAL_SPEND is checked against the complete planned sequence before the first payment. --dry-run shows the plan without paying. Existing artifacts for the same scenario and service are reused by default; --force-pay explicitly authorizes another sequence within both limits.

The three-operation Base Sepolia demonstration costs 0.31 USDC: calculate 0.01, analyze 0.05, and attest 0.25. Safe receipts for every operation are written to artifacts/payment-receipts.json; authorization headers and full wallet addresses are never stored.

The generated report is artifacts/autonomous-agent-profit-report.html. Open it directly or run npm run view-report and visit http://127.0.0.1:4173. It has no remote JavaScript, fonts, CSS, analytics, or chart dependencies.

Commands

| Command | Purpose | | --------------------------------------------- | --------------------------------------------------------------------- | | scenario create | Recreate the deterministic 15-event synthetic ledger | | ledger list | Print local events without calculating profit | | ledger validate | Validate structure against live public OpenAPI | | calculate | Purchase and validate deterministic P&L and cash flow | | analyze | Purchase deterministic operational findings | | attest | Purchase a signed operational report | | report | Render existing safe artifacts without another payment | | run-demo [--json] [--dry-run] [--force-pay] | Plan or run discovery, budgeted payments, verification, and rendering |

Public package commands:

agent-profit doctor --profile testnet
agent-profit discover --profile mainnet
agent-profit quote calculate [events.json] --profile testnet
agent-profit calculate events.json --pay --max-payment 0.01 --max-total-spend 0.01 --max-attempts 1
agent-profit analyze events.json --pay --max-payment 0.05 --max-total-spend 0.05 --max-attempts 1
agent-profit attest events.json --pay --max-payment 0.25 --max-total-spend 0.25 --max-attempts 1
agent-profit report-verify signed-report.json
agent-profit workspace-data-quality WORKSPACE_ID --token-env WORKSPACE_READ_TOKEN

doctor, discover, and quote never sign or pay. Paid commands abort unless an explicit profile, --pay, and all three limits are present. Private keys are loaded only from the ignored X402_BUYER_PRIVATE_KEY environment variable and are never persisted or printed.

The SDK exposes all eight MCP capabilities, including workspace_get_data_quality, through the corresponding HTTP-backed client and CLI operation where applicable.

Audience fit:

• x402 sellers: measure whether a paid API earns more than its model, infrastructure, and acquisition costs.
• agent builders: give an autonomous agent a deterministic profit feedback loop.
• agent platforms: use profit and experiment contribution as evaluation and routing signals.

Signature verification

The verifier fetches /api/v1/signing-keys, canonicalizes the signed manifest independently, recomputes SHA-256, and verifies the Ed25519 signature with Node's cryptography implementation. It never trusts the service's /reports/verify answer as proof. Tests demonstrate that changing one signed value fails verification, unknown keys fail, invalid hashes fail, and report schema versions 1, 2, and 3 are recognized.

Mainnet safety

Use eip155:8453, official Base native USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, and X402_MAX_PAYMENT=0.01 only for an explicitly authorized single calculation. The POC validation used Base Sepolia and spent no mainnet funds.

Quality gates

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run secret-scan
npm audit --audit-level=high

Limitations

• The ledger is intentionally local JSON, not a multi-user database.
• The client validates structure and reconciles counters but never computes replacement profit totals.
• Evidence classifications describe provenance; synthetic and self-reported events are not independently verified.
• The report is operational information, not audited accounting, tax reporting, or financial advice.
• A requested sequence stops before its first payment if either a per-operation or cumulative limit would be exceeded.

An autonomous agent can adapt this client by replacing autonomousBusinessScenario() with its own economic-event producer while keeping the same public-schema validation and payment policies. See ARCHITECTURE.md, PAYMENT_FLOW.md, and SECURITY.md.