Work cycle SDK

The work API records an owner-approved plan and checks the financial receipts against finalized Solana mainnet transactions. It does not hold keys, sign transactions, run a merchant, or promise that a job will earn enough to repay its loan.

A complete recorded cycle has five receipts: borrowing, resource payment, delivery attestation, incoming USDC, and repayment. Repayment is also allowed early so recovering a debt never depends on completing a job. completedCycle is true only when all five receipt kinds are present and the loan has been repaid.

Interfaces

Import WorkCycleClient, createOpenAIWorkAdapter, executeApprovedWorkStep, purchaseWorkResource, and hashWorkArtifact from @towerz/agent-sdk/work-cycle. The PostgreSQL execution journal is available from @towerz/agent-sdk/work-cycle/postgres; shared x402 spending policies are available from @towerz/agent-sdk/x402/postgres.

The API and browser SDK use canonical USDC integer amounts with six decimals. For example, "1000000" means 1 USDC. All financial amounts remain strings or bigint until display.

new WorkCycleClient({ owner, baseUrl, origin }) connects to the API. The base URL must be an HTTPS origin, or localhost for development. origin must match the frontend or caller origin authorized by the server. The default deployment is Solana mainnet. authenticate(signMessage) validates the challenge before asking the caller's wallet to sign the canonical session message. getChallenge and createSession support wallets that implement their own constrained message-signing adapter.

This signature authorizes private work-record access for 15 minutes. It does not grant payment or transaction authority. Session tokens stay in the client instance and are cleared on logout; they are never stored in browser local storage by this SDK. The service stores token hashes, not wallet secrets.

The client exposes status, create/list/get orders, add receipts, cancel an unused draft, and logout. Each request accepts an AbortSignal. Returned orders are checked for owner, deployment, network, known stages, exact amounts and receipt structure before the SDK exposes them. An order URL is an opaque navigation link, not a bearer capability: only its authenticated owner can inspect the record.

A resumable workflow

1. Create an immutable plan containing the agent, exact HTTPS resource URL, merchant recipient, facilitator fee payer, payment cap and expiry. Save the order ID and original client request IDs.
2. Read the agent's accepted credit line and loan terms using the Towerz SDK. Show the proposed amount, fee, term and destination in the owner's transaction approval flow.
3. Call executeApprovedWorkStep for borrowing. Supply a caller-owned transaction callback and a durable WorkExecutionJournal. The helper writes an atomic claim before entering the signer, records a returned signature, then asks the API to verify it. It never retries an uncertain signing attempt.
4. Call purchaseWorkResource with an explicit approval callback, x402 signer, RPC connection, daily budget, durable budget store, and durable execution journal. The helper constructs a policy from the work plan, uses a deterministic request ID and performs at most one signed payment attempt. The API independently verifies settlement before advancing the work order. A merchant-reported receipt alone is not confirmed payment.
5. Perform the research, data or compute work in the caller's environment. Save the output under the caller's retention policy. hashWorkArtifact computes its digest locally; submit only the digest, byte count and media type. The API does not receive its contents.
6. Record an incoming USDC transaction after the customer pays. The API verifies an incoming transfer from a different signing wallet. This is labeled transfer evidence; different wallets do not prove independent people or a commercial sale.
7. Call executeApprovedWorkStep for repayment with an owner-approved Towerz repayment transaction. Principal and fee are checked against the linked on-chain loan. Repayment proposals expose the verified principal-plus-fee amount separately from the resource purchase cap. The caller-owned transaction callback must present and enforce the exact transaction it builds; this helper is not an on-chain restriction on arbitrary wallet software.

getOrder provides durable server-side recovery after a restart. A receipt with pendingReceipts[].state === "pending" has not advanced the cycle. Re-submit that same payload and client request ID to retry verification. Do not repeat the financial action. An HTTP 202 response is pending verification, not settlement confirmation.

If the execution journal contains a signature, executeApprovedWorkStep and purchaseWorkResource resume receipt verification without invoking the signer. Recovered purchases return recovered: true, response: null, and receipt: null: the SDK does not fabricate a merchant response or saved artifact. The caller must persist the resource output under its own retention policy. If it contains an uncertain claim without a signature, including a crash before the merchant returned its transaction signature, stop and reconcile the wallet and chain. All workers and restarts must use the same journal namespace. Changing the namespace partitions replay protection. The journal intentionally has no automatic reset or expiry that could enable a second loan action after a lost response. A caller who changes the journal namespace or edits its database can bypass that protection; database administration is trusted authority.

Expiry stops new borrowing and payments. A transaction finalized within the plan window can still be recorded later for recovery. Repayment remains recordable after expiry.

Agent frameworks

createWorkTools(client) returns framework-neutral structured read-only tools for inspecting a private work order and proposing its next step. createOpenAIWorkAdapter(client) exposes the same tools as Chat Completions function schemas and validates dispatch names and argument shape. Tool results include the owner approval link. These tools never sign, borrow, pay, or repay. Mount them only in an authenticated caller-owned runtime; do not put private owner records on the public MCP service.

This adapter does not claim A2A or AP2 certification. MCP remains a tool interface, and x402 remains the payment protocol.

Evidence and limitations

Financial receipts are verified against finalized mainnet signatures, successful transactions, the deployed Towerz program, canonical USDC, wallet ownership, exact transfer amounts, and the linked loan. Signatures and loans cannot count toward multiple verified work orders. Developer-operated pilots remain labeled separately from unverified external operators. An external wallet is not presented as verified independent adoption.

A delivery digest is an owner attestation. Its recorded timestamp says when the attestation was saved, not when the work was actually completed. A delayed attestation may be saved after an incoming transfer during recovery. Revenue evidence records this distinction; neither receipt sequence nor a USDC transfer proves useful work or commercial demand.

The current resource purchase helper supports one exact, bounded resource payment per work order. It does not support arbitrary merchants, automatic swaps, pooled-fund DeFi investment, or on-chain delegated spending restrictions. The PostgreSQL budget coordinates cooperating workers, while the wallet remains capable of signing actions outside that software policy. Jupiter and Kamino context adapters are read-only; quotes and market data do not authorize trades.

No production customer job, paid merchant result, external audit, or independent adoption is implied by the reference implementation and local tests. Operators must validate their own merchant, work output and economic terms before authorizing real funds.