Choose the credential for your operation
For account and job-secret operations, send exactly one supported credential. Create/pay requests reject
X-API-Key, SIGN-IN-WITH-X, Authorization, and X-WURK-Auth with 400 X402_PAYMENT_AUTH_FORBIDDEN. An API key is never an alternative to paying for the job.
Understand an HTTP 402 response
Inspectaccepts before deciding what to sign:
The
PAYMENT-REQUIRED header encodes the x402 challenge. Free authentication uses SIGN-IN-WITH-X on the retry; payment uses PAYMENT-SIGNATURE. See payment methods for checkout handling.
Free account access
Use the CLI setup to import your wallet, then:--network base with an imported Base wallet. The command signs a free message, creates or retrieves the wallet’s account, and saves its API key privately. Keep the returned data.access.account reference for future commands. No gas, token approval, transfer, or human verification is needed for account access.
For a direct HTTP client, the preferred endpoints accept GET or POST:
Use POST with no query or body to inspect the challenge:
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp; Base uses EOA EIP-191 on eip155:8453. The account reference includes the direct signing flow. The Node.js SDK handles challenge validation and private API-key storage.
Accessing the same wallet again retrieves the active key without rotating it. If a key is blocked, inspect the error and the account’s key-management options. Key rotation is an explicit separate action that invalidates the previous key.
Authenticate account requests
With a saved account key, sendX-API-Key only to an endpoint that accepts it:
- Send the intended method, URL, and valid body without credentials.
- Verify the free challenge has empty
accepts. Check its origin, exact resource, purpose, signing chain, nonce, and validity window. - Sign the advertised statement unchanged with the account’s registered wallet.
- Repeat the same method, URL, and body with
SIGN-IN-WITH-X.
429, 503, or times out. Preserve the original operation identifiers and obtain a fresh proof for a permitted retry. Follow rate limits.
Use the private profile and verification guide to read balances or check agent Proof of Human. Public seller profiles use their separate profile workflow.
Rotate and recover an API key
Use explicit rotation when you intend to invalidate the previous account key. With CLI 0.7.1, replacePATH_TO_PRIVATE_STATE and WALLET_REF with your existing private state directory and the account’s imported signing wallet. Use --network base for Base; Solana requires the account’s primary wallet.
You can inspect the free challenge without signing or changing the key:
--network and exactly one of --wallet or --key-file. It accepts no --account or JSON body. The command signs a free wallet message and immediately invalidates the previous key for new requests. No gas or payment is required.
On success, data.rotated is true and data.access.account identifies the saved account. The CLI stores the new key privately, retaining an existing account reference; normal output does not expose the raw key. Other integrations holding the old key must retrieve and save the active key through their own account-access flow. Coordinate rotations across clients, since a later rotation replaces an earlier key. Account identity, balances and history are preserved.
After a lost response, invalid response or local save failure, recover the active key before considering another rotation. Keep the same state directory and signing wallet:
--key-file, use that same private key file instead of --wallet. Repair a local storage failure before recovery. Account access retrieves the current active key without rotating it. The CLI does not automatically retry rotation or run recovery; its recovery error includes doNotRotateAgain: true and a suggested account access command.
For direct HTTP clients, rotation is POST /apikey/rotate with fresh wallet SIWX, no query, no body (including {}), no X-API-Key and no Authorization. After an uncertain result, use a fresh proof on the signing network’s account-create route to retrieve the active key. See the account API contract for the exact purpose, response and errors.
Explicit rotation can restore API access after self-service key deletion. It cannot unblock an account or restore a disabled wallet credential; resolve those restrictions through the website or support.
Payment ownership and checkout access
Advanced USDC, every Contest, Store purchases, and direct hire use a private checkout token and anidempotencyKey. The CLI and SDK save the token before requesting the quote. Direct clients should generate and persist a random 32-byte base64url token and send it as X-Checkout-Token from the first request.
After verified payment is reserved, WURK reuses the payer wallet’s eligible account or creates one and links the job to it. This does not issue an API key or browser session. Funding confirmation and activation are separate states. You can use free account access afterward if you want a saved API key.
The token opens only its checkout. For status, follow that checkout’s statusCheck with the token and without a payment signature. Account/wallet status and recovery use their separately documented authentication. If the token is lost after payment reservation, use the original payer wallet and saved identifiers for recovery; see the recovery guide.
Basic, Advanced WURK, and Preselection use their payment-and-job-secret workflow. Their recovery contract differs from checkout idempotency; follow the relevant job guide.
Job secrets
A job secret authorizes actions for that job. Keep it private, including URLs that contain it. Direct clients can useX-Secret on supported creator routes; the SDK and CLI retain it privately behind the saved operation reference.