@perkos/agent-sdk 0.1.0 → 0.3.0

package/docs/plans/2026-08-25-stacks-x402-facilitator-design.md

@@ -0,0 +1,143 @@
+# Stacks x402 verifier and facilitator
+
+Date: 2026-08-25
+Status: approved for implementation by the M2 continuation
+
+## Milestone boundary
+
+Milestone 1 is approved and closed. This work is an additive `@perkos/agent-sdk` capability for
+Milestone 2 developer adoption and demo readiness. It does not change, redeploy, or charge a fee
+through the STX or sBTC contracts. It also does not replace the external security review or any
+mainnet/non-team adoption requirement.
+
+The deliverable is a reusable facilitator mechanism, not a hosted production service. It can be
+registered with the official `@x402/core` facilitator and can later power a Next.js route, a
+standalone facilitator, or an agent framework without duplicating Stacks verification logic.
+
+## Approaches considered
+
+### Deploy a hosted facilitator immediately
+
+This would create an immediately callable endpoint, but it also introduces hosting, rate limits,
+availability, durable storage, observability, and incident-response obligations before the core
+verification rules are reviewed. It is deferred.
+
+### Migrate the application middleware first
+
+The current application middleware uses custom `X-X402-*` headers and escrow-balance checks. A
+direct migration before independent transaction verification would make the surface look standard
+without closing its security boundary. It is deferred until the SDK mechanism is merged.
+
+### Add a reusable SDK facilitator with injected state
+
+This provides strict, testable verification and lets each host supply its own fetch implementation
+and atomic replay store. It aligns directly with the public SDK, example, and external-feedback
+parts of M2. This is the selected approach.
+
+## Protocol model
+
+The existing client uses `paymentFlow: "upfront"`: the buyer broadcasts and confirms `fund-job`
+before it asks for the protected resource again. Under the official x402 v2 flow table, upfront
+payments call facilitator settlement before the resource handler; read-only `/verify` is not part
+of the normal resource-server ordering. For this Stacks mechanism, settlement does not broadcast a
+second transaction. It independently observes the already confirmed escrow funding and atomically
+consumes its transaction ID as the one-time payment proof.
+
+The facilitator still implements `verify` because it is part of the standard facilitator API and
+is useful for diagnostics. `verify` never writes replay state. `settle` repeats verification and
+then performs the atomic replay-state transition before returning success.
+
+## Components
+
+`src/x402-facilitator.ts` will contain:
+
+1. `HiroX402TransactionSource`, a read-only client for current v3 transaction/event detail and
+   the chain tip.
+2. Strict parsers for the minimum Hiro response fields needed by the mechanism.
+3. Verification of requirement/payload equality, confirmation depth, freshness, payer, contract
+   call, function arguments, asset transfer event, amount, and client proof block metadata.
+4. `PerkOSX402Facilitator`, implementing the official `SchemeNetworkFacilitator` interface.
+5. `PerkOSX402ReplayStore`, an injected atomic-consume interface.
+6. `InMemoryX402ReplayStore`, safe for examples and one-process tests but explicitly unsuitable
+   for horizontally scaled production.
+
+The default transaction source uses the API URL already resolved by the SDK configuration. No API
+key, private key, signer, fee recipient, or treasury is needed.
+
+## Verification rules
+
+A payment is valid only when all checks pass:
+
+- The payload and supplied requirement are deeply equal and both pass the existing PerkOS x402
+  parser.
+- The transaction ID and claimed payer are valid for the configured Stacks network.
+- Hiro v3 returns a successful, indexed `contract_call` with an anchored block record.
+- The transaction sender equals the payload payer.
+- The contract and function are exactly the configured asset-specific commerce contract and
+  `fund-job`.
+- The decoded contract `job-funded` print event contains the exact job ID and amount. For sBTC, its
+  token principal is the configured canonical token.
+- A matching on-chain transfer event moves the exact requirement amount from the payer to the
+  commerce contract: canonical SIP-010 sBTC for sBTC, or micro-STX for STX.
+- The API block height/hash match any block metadata included in the client proof.
+- The transaction has the configured minimum confirmation count and is no older than the quote's
+  `maxTimeoutSeconds`, with a small configurable clock-skew allowance.
+- The network-prefixed transaction key has not already been consumed.
+
+The event check is mandatory even when a transaction result is `(ok true)`: successful execution
+alone does not prove that the quoted amount and asset moved into escrow.
+
+## Replay and concurrency
+
+The replay key is `${network}:${normalizedTxid}`. `settle` calls an atomic
+`consume(key, record): Promise<boolean>`. Exactly one concurrent caller can receive `true`; every
+later caller receives a replay failure. A production adapter must implement this with a unique
+database constraint or an atomic primitive such as Redis `SET NX`, and should retain records at
+least as long as any protected resource can be delivered.
+
+The in-memory implementation uses a process-local map and is only for tests, examples, local
+development, and a single-process demo. It must not be represented as durable or distributed
+replay protection.
+
+## Security limitation
+
+The current Stacks payload is proof of an already public transaction, not a private off-chain
+authorization bound cryptographically to an HTTP request. Confirmation freshness and first-writer
+replay consumption reduce stale reuse, but a party that obtains the proof before settlement could
+attempt to front-run it. The application must not migrate a high-value production paywall until a
+later design either gives the facilitator the signed transaction before broadcast or adds a
+request-bound payer signature/challenge.
+
+This limitation will be visible in the README and example. The mechanism is appropriate for M2
+integration evidence and controlled pilots, not an unaudited high-value production gateway.
+
+## Errors
+
+Malformed requirements, mismatches, failed transactions, insufficient confirmations, expired
+proofs, missing transfer events, and replay attempts return stable invalid-reason strings. Network
+or malformed API responses fail closed. Settlement never marks a proof consumed until every
+read-only verification check succeeds.
+
+If consumption succeeds, settlement returns the existing funding transaction, payer, Stacks
+CAIP-2 network, and exact atomic amount. It never claims to have broadcast another transaction.
+
+## Testing and evidence
+
+Unit tests will cover sBTC and STX success, official facilitator registration, malformed payloads,
+cross-network/requirement mismatch, wrong sender/contract/function/job/token/amount, missing or
+incorrect print/transfer events, failed or incomplete transaction evidence, insufficient
+confirmation, expiry, block metadata mismatch, API failure, and concurrent replay consumption.
+
+A wallet-free quickstart will inspect the public M1 mainnet sBTC funding transaction through Hiro
+and demonstrate that its contract call and transfer event match the expected escrow fields while
+the facilitator correctly refuses it as an expired x402 proof. It changes no M1 state and consumes
+no replay record. This is additional M2 SDK evidence, not a new M1 claim or adoption credit.
+
+## Follow-up
+
+1. Merge and publish the SDK verifier/facilitator.
+2. Obtain external technical feedback and include the module in the recorded M2 SDK demo.
+3. Add a durable replay-store adapter and thin hosted HTTP facilitator.
+4. Replace the application's custom x402 middleware only after the request-binding limitation has
+   an accepted mitigation.
+5. Continue the external security review and mainnet/non-team adoption work in parallel.

package/docs/plans/2026-08-25-stacks-x402-v2-design.md

@@ -0,0 +1,139 @@
+# Stacks x402 v2 foundation
+
+Date: 2026-08-25
+Status: approved foundation for implementation
+
+## Milestone 2 alignment
+
+Milestone 1 is approved and closed. This work must not redeploy, replace, or add fee behavior to
+the M1 mainnet contracts. It is an additive SDK adapter intended to make the existing STX and sBTC
+job lifecycle easier for external developers and agent frameworks to adopt during Milestone 2.
+
+The authoritative M2 acceptance work remains the public SDK, working documentation and example,
+external security review, recorded SDK demo, mainnet adoption, non-team participation, and external
+technical feedback. This x402 foundation can support the SDK/example/adoption portions, but does
+not by itself complete M2 and must not delay the security review or adoption outreach.
+
+## Decision
+
+Use the official `@x402/core` v2 envelope and HTTP header codecs, then implement a narrow Stacks
+escrow adapter around the existing `PerkOSClient`. The first version represents a confirmed
+`fund-job` transaction as the scheme-specific payment proof. It does not implement a hosted
+facilitator, protocol revenue, metering, or a new smart contract.
+
+The wire contract uses:
+
+- x402 version `2`;
+- `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, and `PAYMENT-RESPONSE` header formats from
+  `@x402/core/http`;
+- CAIP-2 network identifiers `stacks:1` for mainnet and `stacks:2147483648` for testnet;
+- scheme `exact` because the job budget is an exact atomic amount;
+- asset transfer method `perkos-escrow-v1` to prevent a direct-transfer facilitator from
+  misinterpreting an escrow requirement;
+- payment flow `upfront` for the HTTP resource because the escrow must be confirmed before the
+  protected endpoint proceeds. The later job completion remains governed by the existing neutral
+  evaluator and escrow contract.
+
+## Alternatives considered
+
+### Keep the existing custom `X-X402-*` headers
+
+This is the smallest code change, but it is not the current x402 v2 transport and makes ecosystem
+integration harder. It is rejected for new SDK work. The application migration will happen only
+after this SDK foundation is merged and tested.
+
+### Adopt a third-party Stacks x402 package directly
+
+`@t402/stacks` and `x402-stacks` provide useful reference implementations. Their transfer and
+signer assumptions do not match the PerkOS job escrow lifecycle or the SDK's injected signer and
+fail-closed spending policy. A direct dependency would create two signing/policy stacks. They are
+not used in the foundation.
+
+### Official x402 core plus a PerkOS Stacks adapter
+
+This keeps the rapidly evolving transport and schemas with the x402 Foundation while retaining
+PerkOS-specific escrow validation, exact post-conditions, Leather support, confirmation tracking,
+and spending limits. This is the selected approach.
+
+## Components
+
+`src/x402.ts` will provide:
+
+1. Network conversion between the SDK network names and Stacks CAIP-2 identifiers.
+2. A payment-requirement builder derived from a resolved `PerkOSClient` configuration.
+3. Strict parsing of PerkOS escrow requirements and confirmed-funding proofs.
+4. `PerkOSX402SchemeClient`, an `@x402/core` scheme client that uses the existing SDK to inspect
+   the job, enforce an exact budget, fund it through the configured signer, wait for terminal
+   confirmation, and return a proof containing the transaction ID.
+5. Re-exported x402 v2 header codecs so consumers do not recreate base64 JSON handling.
+
+The adapter accepts a small structural client interface rather than a private key or wallet
+implementation. The production `PerkOSClient` satisfies the interface; tests can provide a
+deterministic in-memory client.
+
+## Data flow
+
+```text
+Buyer agent                Resource server             Stacks
+     | GET/POST resource          |                       |
+     |--------------------------->|                       |
+     | 402 + PAYMENT-REQUIRED     |                       |
+     |<---------------------------|                       |
+     | validate requirement       |                       |
+     | inspect job/budget         |                       |
+     | fundJob via SDK signer --------------------------->|
+     | wait for confirmation ---------------------------->|
+     | PAYMENT-SIGNATURE          |                       |
+     | (confirmed tx proof)       |                       |
+     |--------------------------->|                       |
+     |                            | facilitator/verification is a later PR
+```
+
+The `PAYMENT-SIGNATURE` name is the x402 transport field for a scheme-specific payment payload.
+For this foundation, its Stacks payload is a confirmed transaction proof rather than an EVM
+EIP-3009 signature.
+
+## Validation and failure handling
+
+- Reject protocol versions other than v2.
+- Reject non-Stacks or cross-network requirements.
+- Require positive decimal atomic amounts and job IDs.
+- Require the configured commerce contract as `payTo`.
+- Require the configured sBTC asset identifier for sBTC and `STX` for STX.
+- Require the on-chain job to exist, remain open, and have exactly the quoted budget.
+- Reuse the SDK spending policy, signer/network checks, post-conditions, and confirmation tracker.
+- Return a payload only after a `success` confirmation. Pending, abort, dropped, and timeout states
+  are payment failures.
+- Never accept a transaction ID as proof of payment without a later facilitator/server verifying
+  the transaction, contract call, sender, amount, job, and replay status.
+
+## Security boundary and known limitation
+
+This PR creates and serializes payment proofs; it does not make an HTTP resource safe to monetize.
+A production resource server still needs an independent Stacks facilitator/verifier and replay
+store. The verifier must hydrate the transaction, match it to the accepted requirement, confirm
+successful escrow funding, and prevent the same transaction from authorizing multiple purchases.
+
+No secret, private key, treasury address, protocol fee, or production endpoint is introduced.
+
+## Testing
+
+The implementation will cover:
+
+- CAIP-2 network mapping;
+- STX and sBTC payment-requirement construction;
+- official x402 header encode/decode round trips;
+- invalid version, network, amount, asset, payee, metadata, and proof rejection;
+- exact job-budget validation;
+- successful confirmed funding through a fake client;
+- failure on non-success terminal confirmations;
+- compatibility with `@x402/core`'s `x402Client` registration and payload creation.
+
+## Follow-up sequence
+
+1. Merge this SDK foundation.
+2. Build a read-only Stacks verifier/facilitator with replay protection and testnet evidence.
+3. Replace the application's custom `X-X402-*` middleware with the SDK v2 adapter.
+4. Add an M2 example/demo and use it for external developer feedback and adoption outreach.
+5. Consider metering and protocol revenue only as a separate, reviewed product phase that does
+   not alter the approved M1 contracts or block M2 acceptance.

package/docs/plans/2026-08-27-x402-paying-flow-design.md

@@ -0,0 +1,125 @@
+# Nayori x402 paying flow design
+
+Date: 2026-08-27
+
+Status: approved for implementation
+
+## Objective
+
+Add a payer-side TypeScript flow for Nayori's direct Stacks x402 profile. The same immutable
+payment intent must support an interactive Leather wallet and an automated agent whose key stays
+inside an application-owned KMS, HSM, secret manager, or wallet service. The SDK prepares and
+validates the payment; it does not broadcast. The Nayori facilitator remains the only component
+authorized to reserve and broadcast a submitted payment.
+
+This increment does not modify or redeploy the approved Milestone 1 contracts, enable Platform
+settlement, or claim Milestone 2 transaction/adoption evidence.
+
+## Constraints and external behavior
+
+- Direct payments use the existing `stacks-signed-tx-v1` profile for STX, sBTC, and USDCx.
+- `PaymentIntent` is deterministic, serializable, request-bound, and contains no private material.
+- The SDK must validate the trusted quote, accepted x402 requirement, request digest, payer,
+  recipient, asset, atomic amount, fee, nonce, signature, memo, and post-conditions before returning
+  settlement input.
+- A signer receives only an immutable intent and the canonical unsigned transaction.
+- Leather integration uses the current Stacks Connect `stx_signTransaction` method with
+  `broadcast: false`; a missing signed transaction is a failure even if a wallet returns a txid.
+- Headless integration delegates signing to an application callback. The SDK never accepts,
+  requests, stores, or logs the agent's private key.
+- Spending policy is mandatory and fail-closed. An LLM or agent cannot override its decision.
+- Session limits count signed authorizations, not confirmed settlements. This conservative rule
+  prevents repeated signing after an ambiguous network result.
+
+## Public API
+
+The new module exports:
+
+- `NayoriX402PaymentIntent` and `createNayoriX402PaymentIntent`;
+- `NayoriX402PaymentPolicy`, its explicit configuration, and read-only session usage;
+- `NayoriX402PaymentSigner` as the common signer contract;
+- `LeatherSigner`, a Stacks Connect callback adapter;
+- `PolicySigner`, a remote/headless signing callback adapter;
+- `NayoriX402PaymentClient`, which builds, authorizes, signs, verifies, and returns the exact input
+  accepted by the hosted `/v1/x402/settle` route.
+
+The client input contains the signed quote bundle returned by Nayori, the protected request, fee,
+and nonce. Address and compressed public key come from the signer. The output contains
+`signedQuote`, `paymentRequirements`, `paymentPayload`, `request`, and locally verified payment
+metadata. It never broadcasts.
+
+## Intent and transaction construction
+
+Intent construction first normalizes the quote and proves that:
+
+1. the protected method, canonical URL, and body digest match the quote;
+2. the accepted x402 requirement is exactly the requirement derived from that quote;
+3. the quote is currently valid with the configured clock-skew allowance;
+4. the signer's compressed public key derives the declared Stacks payer address;
+5. fee and nonce are canonical unsigned integers.
+
+The intent ID is a SHA-256 digest over a domain-separated canonical representation containing the
+quote fingerprint, payer, public key, fee, and nonce. The signed transaction is constructed as:
+
+- STX: a native token transfer with the quote fingerprint in the memo;
+- sBTC/USDCx: the canonical SIP-010 `transfer` call with the payer and recipient principals, the
+  fingerprint in the optional memo, deny mode, and one exact fungible-token post-condition.
+
+All three paths are standard, non-sponsored transactions. Fee and nonce are provided explicitly so
+transaction preparation is deterministic and performs no hidden network request.
+
+## Policy and concurrency
+
+Policy configuration explicitly lists allowed networks, assets, recipients, and HTTPS origins,
+plus per-transaction and per-session atomic limits for every allowed asset and a maximum fee in
+micro-STX. Optional merchant IDs and a minimum remaining quote lifetime further narrow authority.
+
+Authorization reserves both payment amount and fee synchronously before asynchronous signing. The
+reservation is committed after a valid signed transaction is produced, or released if building,
+signing, or local verification fails. Active reservations are included in session-limit checks, so
+concurrent agent calls cannot oversubscribe the budget. A committed intent cannot be signed again
+by the same policy instance.
+
+## Signer boundaries
+
+`LeatherSigner` is configured with the connected address, compressed public key, and an injected
+Stacks Connect-compatible request function. It calls only:
+
+```text
+stx_signTransaction({ transaction: unsignedHex, broadcast: false })
+```
+
+`PolicySigner` is configured with the same public identity and a remote callback. That callback may
+talk to a KMS/HSM/wallet service and must return a fully signed serialized transaction. No example
+introduced for this payer flow uses an environment variable or local raw private key. The older,
+explicitly opt-in escrow lifecycle example remains separate from this x402 custody boundary.
+
+Neither signer result is trusted. The client runs the existing pure x402 verifier and additionally
+checks payer, nonce, fee, non-sponsored authorization, and the canonical intent fields before
+committing policy usage.
+
+## Errors and observability
+
+Invalid quote context returns `X402_INVALID`; policy rejection returns the existing `POLICY_DENIED`
+or `POLICY_LIMIT_REQUIRED`; signer cancellation or malformed output returns `SIGNING_FAILED`.
+Errors include stable, non-secret context such as intent ID, asset, or quote ID. Signed quote tokens,
+request bodies, unsigned/signed transaction bytes, and callbacks are not included in error details.
+
+## Tests and release gate
+
+Regression coverage must include all three assets, Leather `broadcast: false`, remote signing,
+request/requirement mismatch, public-key mismatch, fee and amount limits, recipient/origin denial,
+quote expiry, signer mutation, invalid signatures, cancellation, concurrent reservation, release on
+failure, and duplicate-intent prevention. `npm run verify`, `npm audit --audit-level=high`, package
+contents inspection, and a clean-room consumer import are required before the PR is opened.
+
+## Primary references
+
+- Stacks Connect `request` API and normalized `stx_signTransaction` result:
+  https://docs.stacks.co/reference/stacks.js/stacks-connect/request/request
+- Stacks Connect wallet compatibility, including Leather support:
+  https://docs.stacks.co/stacks-connect/wallet-support
+- Stacks transaction construction and unsigned transaction primitives:
+  https://docs.stacks.co/stacks.js/build-transactions
+- Stacks node raw transaction broadcast boundary:
+  https://docs.stacks.co/reference/api/stacks-node-rpc/transactions

package/examples/x402-facilitator.ts

@@ -0,0 +1,69 @@
+import {
+  HiroX402TransactionSource,
+  InMemoryX402ReplayStore,
+  PerkOSX402Facilitator,
+  createPerkOSX402PaymentRequired,
+  resolveConfig,
+  type PaymentPayload,
+} from "@perkos/agent-sdk";
+
+const transaction =
+  "0xaf4129fe46fc913fda7b9fa87543f05fc5f4430b9b5f26a46f9c3032ea0fcbd4";
+const payer = "SP2K7PV5NXBNRV510S6DCA6RFMTFHAF3ZPK6ZSXPH";
+const blockHeight = 8_650_821;
+const blockHash =
+  "0x46786964695d632ce40d54e5a94f5e74bcaf4fc995ff45c9ae913be0020e402d";
+const config = resolveConfig({ network: "mainnet" });
+const paymentRequired = createPerkOSX402PaymentRequired(config, {
+  resource: {
+    url: "https://nayori.example/evidence/m1-job-1",
+    description: "Read-only x402 verifier evidence",
+    mimeType: "application/json",
+    serviceName: "Nayori",
+  },
+  asset: "sbtc",
+  jobId: 1n,
+  amount: 10_000n,
+  maxTimeoutSeconds: 3_600,
+});
+const paymentPayload: PaymentPayload = {
+  x402Version: 2,
+  resource: paymentRequired.resource,
+  accepted: paymentRequired.accepts[0]!,
+  payload: {
+    transaction,
+    payer,
+    jobId: "1",
+    amount: "10000",
+    asset: "sbtc",
+    commerceContract: config.contracts.sbtcCommerce,
+    blockHeight,
+    blockHash,
+  },
+};
+const transactionSource = new HiroX402TransactionSource({ network: "mainnet" });
+const facilitator = new PerkOSX402Facilitator({
+  config,
+  transactionSource,
+  replayStore: new InMemoryX402ReplayStore(),
+});
+
+const verification = await facilitator.verify(
+  paymentPayload,
+  paymentRequired.accepts[0]!
+);
+if (verification.isValid || verification.invalidReason !== "payment_expired") {
+  throw new Error(
+    `Expected the historical proof to be rejected as expired, received ${JSON.stringify(verification)}`
+  );
+}
+
+console.log({
+  transaction,
+  observedContract: config.contracts.sbtcCommerce,
+  observedAsset: paymentRequired.accepts[0]!.asset,
+  observedAmount: paymentRequired.accepts[0]!.amount,
+  verification,
+  note:
+    "The facilitator matched the public funding call and transfer events, then failed closed because this historical transaction is outside the x402 payment window. No state was changed.",
+});

package/examples/x402-foundation.ts

@@ -0,0 +1,30 @@
+import {
+  createPerkOSX402PaymentRequired,
+  decodePaymentRequiredHeader,
+  encodePaymentRequiredHeader,
+  resolveConfig,
+} from "@perkos/agent-sdk";
+
+const config = resolveConfig({ network: "mainnet" });
+const paymentRequired = createPerkOSX402PaymentRequired(config, {
+  resource: {
+    url: "https://agent.example/jobs/7/fund",
+    description: "Fund an existing PerkOS agent job escrow",
+    mimeType: "application/json",
+    serviceName: "Nayori",
+    tags: ["agents", "escrow"],
+  },
+  asset: "sbtc",
+  jobId: 7n,
+  amount: 25_000n,
+});
+
+const header = encodePaymentRequiredHeader(paymentRequired);
+const decoded = decodePaymentRequiredHeader(header);
+
+console.log({
+  headerName: "PAYMENT-REQUIRED",
+  header,
+  decoded,
+  note: "Envelope-only example: no wallet, transaction, or facilitator is used.",
+});

package/examples/x402-payment-intent.ts

@@ -0,0 +1,81 @@
+import {
+  NayoriX402PaymentPolicy,
+  buildNayoriX402UnsignedPaymentTransaction,
+  createNayoriX402PaymentIntent,
+  createNayoriX402PaymentRequirements,
+  createNayoriX402Quote,
+} from "@perkos/agent-sdk";
+
+const payer = "ST1THWXQ8368SDN2MJGE4BMDKMCHZ2GSVTSQDA7QF";
+const payerPublicKey =
+  "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798";
+const payTo = "ST3AZN3BSQYJ5VWMNG92N88Z4G9498VYSHDZD9EK";
+const now = Math.floor(Date.now() / 1_000);
+const request = {
+  method: "POST",
+  url: "https://api.example.com/v1/weather",
+  body: JSON.stringify({ city: "Miami" }),
+} as const;
+
+const quote = await createNayoriX402Quote({
+  quoteId: "quote-payer-quickstart",
+  merchantId: "merchant-weather",
+  network: "testnet",
+  asset: "usdcx",
+  amount: 100_000n,
+  payTo,
+  ...request,
+  issuedAt: now,
+  expiresAt: now + 300,
+});
+const paymentRequirements = await createNayoriX402PaymentRequirements(quote);
+const intent = await createNayoriX402PaymentIntent({
+  quote,
+  paymentRequirements,
+  request,
+  payer,
+  publicKey: payerPublicKey,
+  fee: 300n,
+  nonce: 7n,
+  nowSeconds: now,
+});
+const policy = new NayoriX402PaymentPolicy(
+  {
+    allowedNetworks: ["testnet"],
+    allowedAssets: ["usdcx"],
+    allowedRecipients: [payTo],
+    allowedOrigins: ["https://api.example.com"],
+    allowedMerchantIds: ["merchant-weather"],
+    maxPerTransaction: { usdcx: 100_000n },
+    maxPerSession: { usdcx: 500_000n },
+    maxFeePerTransaction: 500n,
+    maxFeePerSession: 2_500n,
+  },
+  () => now
+);
+const authorization = policy.reserve(intent);
+const unsignedTransaction = await buildNayoriX402UnsignedPaymentTransaction(intent);
+
+console.log(
+  JSON.stringify(
+    {
+      status: "ready-for-signature",
+      intentId: intent.intentId,
+      quoteId: intent.quoteId,
+      asset: intent.asset,
+      amount: intent.amount,
+      payer: intent.payer,
+      payTo: intent.payTo,
+      fee: intent.fee,
+      nonce: intent.nonce,
+      quoteFingerprint: intent.quoteFingerprint,
+      unsignedTransactionBytes: unsignedTransaction.length / 2,
+      policyRemaining: authorization.remainingThisSession.toString(),
+      broadcast: false,
+    },
+    null,
+    2
+  )
+);
+
+authorization.release();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perkos/agent-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TypeScript SDK for agent identity, escrow settlement, and reputation on Stacks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,17 +29,23 @@
     "prepublishOnly": "npm run verify",
     "prequickstart": "npm run build",
     "quickstart": "node --import tsx examples/quickstart.ts",
+    "prequickstart:x402": "npm run build",
+    "quickstart:x402": "node --import tsx examples/x402-foundation.ts",
+    "prequickstart:x402:facilitator": "npm run build",
+    "quickstart:x402:facilitator": "node --import tsx examples/x402-facilitator.ts",
+    "prequickstart:x402:payer": "npm run build",
+    "quickstart:x402:payer": "node --import tsx examples/x402-payment-intent.ts",
     "prequickstart:testnet": "npm run build",
     "quickstart:testnet": "node --import tsx examples/testnet-lifecycle.ts"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/PerkOS-xyz/PerkOS-Agent-SDK.git"
+    "url": "git+https://github.com/PerkOS-xyz/PerkOS-Nayori-Agent-SDK.git"
   },
   "bugs": {
-    "url": "https://github.com/PerkOS-xyz/PerkOS-Agent-SDK/issues"
+    "url": "https://github.com/PerkOS-xyz/PerkOS-Nayori-Agent-SDK/issues"
   },
-  "homepage": "https://stacks.perkos.xyz",
+  "homepage": "https://nayori.ai",
   "keywords": [
     "ai-agents",
     "agentic-commerce",
@@ -58,7 +64,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@stacks/transactions": "^7.6.0"
+    "@stacks/transactions": "^7.6.0",
+    "@x402/core": "^2.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",