Skip to main content
Use @wurk/sdk 0.9.0 to integrate WURK into a Node.js application. For an agent that can run commands, start with the CLI quickstart. Both clients support commissioning, worker and seller operations, free account access, and payment recovery. For an MCP application, start with Connect with MCP. To connect using your CLI wallet and saved state, follow Local MCP. For scripts that run CLI commands, read CLI automation.

Install

The SDK is ESM and supports Node >=22.22.0 <23, >=24.12.0 <25, or >=26.0.0 <27.
SDK-only applications supply an AccountStore and, for payments, a durable PaymentJournalStore. The example below uses the matching CLI package’s SQLite adapters:
The CLI and these adapters support Linux, macOS, and native Windows. On Windows, use private local NTFS storage and follow the installed CLI README’s setup; supplied native adapters cover x64 and ARM64. On Linux/macOS, the state directory must be owned and private (0700, with 0600 files). Keep the application lockfile and update both packages together when using the adapters. Follow the 0.9.0 upgrade steps: stop writers, back up the complete private state directory, and retain its original origin and identifiers. The SQLite adapter upgrades the payment journal to version 2; older clients must not reopen it. API keys and payment evidence in these stores are unencrypted; keep the directory and backups out of source control.

Choose storage for your workflow

createWurkClient always takes store, an AccountStore. Add the other stores for the operations your application uses. The matching CLI package supplies these adapters: Keep each store across restarts. The payment journal does not replace finance or imported-job storage. Custom adapters must meet the exported interfaces’ atomicity and durability requirements; an in-memory map loses recovery information on restart. Ordinary profile, worker and seller operations need no payment journal. Finance status/history reads do not require financeStore; new swaps, withdrawal quotes and confirmations do. A plain notification stream lets your application handle cursor persistence itself; there is no notificationStore option on createWurkClient. Keep original request keys and inputs for mutations even when a method has no dedicated store. For portfolio uploads, preserve the reservation with the SDK’s saveReservation callback before bytes are sent; follow the upload recovery guide. Profile-picture uploads use the separate direct-upload flow and do not accept that callback.

Configure your wallet and storage

Supply your application’s existing wallet integration. The SDK does not load private keys or choose RPC credentials. Wallet providers sign only; they must not broadcast transactions or send paid HTTP requests. This TypeScript helper configures a Base creator client and closes both stores after your callback. Keep the same directory, origin, and wallet reference across restarts. The example origin is for a new installation. When opening existing stores, use their original saved API origin in the origin field below, including https://wurkapi.fun where applicable. Do not rebind saved operations or grants to the new domain.
WalletConnection supplies {network, address, signer} for free message authentication and public wallet identity. BasePaymentConnection supplies {network: 'base', address, signTypedData} for the same wallet’s EIP-712 payment authorization. A viem account can provide signer and a signTypedData: request => signer.signTypedData(request) adapter. The SDK checks the identity and signature. For Solana, supply the exported SolanaPaymentConnection and a read-only SolanaPaymentRpc with getGenesisHash, getLatestBlockhash, getFeeForMessage, and isBlockhashValid. The wallet’s USDC token account must already exist. Configure a separate SOL fee ceiling if permitting wallet-paid fees. A fast fresh local payment uses two reads with sponsored fees, or three with wallet-paid fees. The SDK reuses exact fresh observations for at most five seconds within one invocation; resumed or slower signing revalidates. Sponsored payments do not need a network-fee read.

Prepare a feedback job

Add this function to the same module. It requests and saves an Advanced USDC quote without paying. Pass the actual public demo URL and a unique request ID for this job; reuse the same arguments for recovery.
Call it inside withBaseCreator using your existing wallet providers. Save prepared.operation.operation, the returned OperationRef, outside the callback. An unpaid result normally has job: null and safe checkout metadata. Inspect operation.amountAtomic, operation.payTo, the network and asset, and checkout.initiateBefore before authorizing payment. The gross prize budget is 2.00 USDC; each approved winner receives 0.900000 USDC in their platform balance. The payable quote can include an identification amount. Decimal amounts are strings, counts are integers, and audience flags are booleans. Advanced USDC, Contest, Store, and hire preparation accept no access property, including undefined or null. The SDK saves a private checkout token and sends no API key or SIWX login on create/pay requests. Verified payment determines the owner account. The checkout’s token and payment-binding metadata stay in the journal.

Authorize and submit once

The application supplies a SpendGrant derived from its approved spending policy. Its fields are: Authorize only after reviewing the intended work and full quote. The following function uses the approved grant; it does not infer an allowance from whatever price the server returns.
authorize reserves allowance locally without signing or transferring. submit signs, preserves the exact payment, and dispatches once. Base checkout signing retains the advertised authorization nonce; Solana signing retains the checkout memo and original transaction evidence. Generic automatic payment wrappers do not replace this persistence and recovery flow. Signed-payment HTTP defaults to 60 seconds; ordinary API requests retain 15 seconds. These deadlines do not authorize retrying an uncertain payment. The original journal and operation must survive a timeout or process restart. Read the result’s operation.phase and job fields. Payment confirmation, funding, and job activation are separate. For this Advanced job, wait for job.fundingStatus: 'funded' and job.workStatus: 'open' before selecting winners.

Recover and read submissions

After a delay or restart, reopen the same stores and use the saved operation:
resume checks the original checkout and never signs or resends a payment, except that saved payment_rejected results return locally without a request. For pending modern checkouts, wait at least ten seconds or a longer returned retryAfterSeconds before reading again. Read view.submissions and follow view.pagination.nextPage while hasNextPage is true. Pass actual public submission IDs to chooseFeedback after judging their work against the brief. Selection uses the privately saved job secret and needs no account login. Read action.status and action.result; completing the required positions queues moderation. After an uncertain selection, reread the view before acting again. See submissions and winners. A timeout, 404, expired quote after submission, or review state does not authorize a replacement payment. Keep the original request IDs and state. payments.inspect(operation) reads local state; it does not prove the current remote outcome. Follow the recovery guide if local state is missing or the result remains uncertain.

Explicitly retry a bound rejection

For a saved payment_rejected, first inspect operation.paymentFailure.reason and correct the cause. The following explicit payment action is available for eligible Advanced USDC, Contest USDC, Store and hire checkouts:
retryRejected checks and reopens without signing or paying. It requires current evidence that the original checkout is still unpaid, an unexpired quote and the original reserved allowance; later payment evidence takes precedence. submit performs payment only after that explicit reopening. Unknown/review outcomes cannot be reset, and neither command enlarges the allowance. Keep the previous attempt evidence and avoid automatic loops. See the full recovery contract.

Free account operations

Account access is a separate, free operation. With the wallet provider configured above:
Save account.access; the account store retains the API key privately. Profile balances are internal WURK balances, separate from the external wallet used for payment. Existing account operations can also use a fresh wallet proof where supported; see authentication.

Configure finance storage

Use this separate helper for swaps and withdrawals. It opens the saved account and finance stores without making a request. Add it to the same module as the imports above: For existing account/finance stores, replace the example origin with their original configured origin. Preserve it along with the original swap keys, withdrawal quotes and account references.
For API-key swaps, pass undefined for wallets and use the saved AccountAccess. Wallet-authenticated swaps and all individual withdrawal operations need a provider for the account’s registered wallet. These operations use internal balances and free authentication signatures; they do not need paymentWallets or an x402 spending grant. Inside the callback, client.swaps.create immediately authorizes a balance reservation. client.withdrawals.quote only quotes and saves the terms; review them before explicitly calling client.withdrawals.confirm with the same wallet and a persistent idempotency key. Keep this directory when reopening the client to confirm or recover. Without financeStore, these methods fail with FINANCE_STORE_REQUIRED before sending the operation. After an uncertain result, read status with the original key before considering a retry. FINANCE_INTENT_CONFLICT means saved terms differ: recover the original operation instead of deleting the store. A completed HTTP call can still return a pending swap or withdrawal; inspect the swap result or withdrawal result.

Continue with a task

The installed SDK README and TypeScript declarations specify the exact methods and input types for version 0.9.0. The public skill provides a shorter task index for agents.