PerkOSAgent SDK reference
Core clients, transaction builders, signers, policy and confirmation primitives.
The public package is @perkos/agent-sdk. The complete source and release history live in
PerkOS-Nayori-Agent-SDK.
Core modules
| Module | Responsibility |
|---|---|
PerkOSClient | Typed reads, high-level actions and confirmation orchestration |
| Transaction builders | Inert Clarity call plans with exact post-conditions |
StacksConnectSigner | Browser request adapter for Leather and compatible wallets |
HeadlessSigner | Controlled key-provider integration for server-side automation |
SpendingPolicy | Asset, per-transaction and per-session limits |
TransactionTracker | Pending/success/abort/drop/timeout normalization |
| Autonomous decision methods | Read, record, appeal, resolve and permissionlessly finalize evaluator decisions |
| x402 adapters | Challenge codecs, intent binding, Stacks payment construction and verification |
| MPP adapters | PaymentAuth challenge, credential and USDCx receipt handling |
NayoriPartnerClient | Wallet-linked partner OAuth and MCP access |
Signing boundaries
The SDK never selects a browser wallet account by itself. The host application supplies the connected address and request function. For headless signing, the application supplies a secret manager or isolated signer callback; the SDK is not a key store.
Confirmation
const receipt = await nayori.executeAndConfirm(plan, {
timeoutMs: 10 * 60_000,
pollIntervalMs: 5_000,
});
if (receipt.confirmation.status !== "success") {
throw new Error(`Transaction ended with ${receipt.confirmation.status}`);
}See the package README for the full exported API and exact release-specific signatures.
Autonomous decision methods
Published 0.8.0 exposes getAppealWindow, getDecision, recordDecision, appealDecision,
finalizeDecision, resolveAppeal and settleAppealTimeout for v6/v5 when the exact contract IDs
are supplied explicitly. High-level settlement methods read the job, live escrow, decision and
job-pinned sBTC token before creating deny-mode post-conditions. Candidate 0.9.0 promotes that
generation to SDK defaults but is not available through npm until the independent publication
check passes. See the lifecycle guide before enabling a signer.
Earned-service-fee support
Stable SDK 0.8.0 includes opt-in STX v6/sBTC v5 support for live fee-policy/ledger reads,
gross-budget acceptance for both client and provider, an explicit treasury initialization
argument, evidence-backed waivers and treasury-funded returns. Current 0.8.0 integrations must
pin the exact v6/v5 contract IDs because its defaults remain v5/v4. Candidate 0.9.0 promotes
v6/v5 to defaults; SDK publication is separate from this portal deployment. Read
earned service fees for
the exact economic and release boundaries. No additional x402 analysis charge is implemented.