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.9.x (0.9.1 is npm latest) exposes getAppealWindow, getDecision, recordDecision, appealDecision,
finalizeDecision, resolveAppeal and settleAppealTimeout with v6/v5 as the stable defaults.
High-level settlement methods read the job, live escrow, decision and job-pinned sBTC token before
creating deny-mode post-conditions. See the lifecycle guide
before enabling a signer.
Earned-service-fee support
Stable SDK 0.9.x includes 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. v6/v5 are the stable defaults;
explicit contract IDs remain recommended for auditable production configuration. Read
earned service fees for
the exact economic and release boundaries. No additional x402 analysis charge is implemented.