SDK

The Sovereign SDK is a proposal-only client. It lets agents submit economic intents, query provenance, create trade plans, and run risk checks. It does not expose any signing surface.

Initialize client

Create a client pointed at your running API instance.

import { SovereignClient } from "@sovereign/sdk";

const client = new SovereignClient({
  baseUrl: "http://localhost:3002",
  agentId: "akasha_agent"
});

Submit paid data intent

Propose a paid data request to a procurement wallet. The runtime evaluates the constitution and returns a DecisionPacket or a denial.

const result = await client.proposeIntent({
  walletId: "wallet_procurement_demo",
  agentId: "akasha_agent",
  kind: "mcp.paid_data_request",
  merchantId: "merchant_akasha_market_data",
  routeId: "route_eth_snapshot_v1",
  taskId: "eth_market_cycle_001",
  idempotencyKey: "eth_snapshot_001"
});

// result.status === "approved" | "denied" | "escalated"
// result.decisionPacket (when approved)
// result.artifactId (when executed)

Create trade plan

Create a trade plan from a paid data artifact. The plan is not executed until a risk check passes and the trading wallet approves it.

const plan = await client.createTradePlan({
  artifactId: result.artifactId,
  symbol: "ETH/USD",
  direction: "long",
  size: "0.1",
  rationale: "ETH cycle bottom signal from market data"
});

Run risk check

Run a deterministic risk evaluation on a trade plan before requesting execution. The risk check is required by the trading wallet constitution.

const risk = await client.runRiskCheck(plan.planId);

// risk.passed === true | false
// risk.signals: position size, concentration, leverage, volatility

Paper execute

Request paper execution of a risk-approved trade plan. Live execution is denied unless explicitly escalated and approved by the wallet constitution.

const order = await client.executePaperTrade({
  planId: plan.planId,
  riskCheckId: risk.checkId,
  walletId: "wallet_trading_demo"
});

// order.status === "filled" | "denied" | "escalated"
// order.paperOrderId

Get provenance

Retrieve the full provenance chain for a data artifact. Returns the merchant, route, wallet, constitution version, decision packet, agent, and any downstream artifacts or trade plans that reference this data.

const provenance = await client.getProvenance(artifactId);

// provenance.artifact
// provenance.merchant
// provenance.route
// provenance.wallet
// provenance.constitutionVersion
// provenance.decisionPacket
// provenance.downstream: TradePlan[]

What the SDK does not expose

These operations are architecturally absent from the SDK. They are not gated — they do not exist in the interface.

• signTransaction — not available
• sendTransaction — not available
• approveToken — not available
• rawCall — not available
• modifyConstitution — not available
• changeBudget — not available
• approveMerchant — not available
• enableLiveTrading — not available