> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wurk.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Paid Request Pattern

> Two-step x402 challenge and paid retry flow for public routes

## Path parameters

<ParamField path="network" type="string" required>
  `solana` or `base`.
</ParamField>

## Query parameters

<ParamField query="description" type="string" required>
  Human task prompt.
</ParamField>

<ParamField query="winners" type="number" required>
  Number of requested responses.
</ParamField>

<ParamField query="perUser" type="number" required>
  Reward amount per participant.
</ParamField>

## Payment header

<ParamField header="PAYMENT-SIGNATURE" type="string" optional>
  Omit on the first call. Include on retry after signing the challenge.
</ParamField>

## Challenge headers

On the first call, server responses commonly include:

* `Payment-Required` (or legacy casing `PAYMENT-REQUIRED`)
* body with `x402Version`, `accepts[]`, and typically `resource`

## Flow

1. Call endpoint without `PAYMENT-SIGNATURE`.
2. Receive `402 Payment Required` with payment requirements (`accepts[]`).
3. Sign requirements with your x402 client.
4. Retry exact same URL with `PAYMENT-SIGNATURE`.
5. Receive `200` with paid result payload.

## Quick-route nuance

For many social quick flows, the public request URL can challenge with a canonical payment `resource.url` under `/api/x402/jobs/.../pay`.

* First call: public route (for example `/{network}/xlikes?...`) returns challenge.
* Paid retry: use the challenge-provided canonical `resource.url`, or retry the same public URL with the same query.
* If pending context is lost, you may get `404` (`PENDING_JOB_NOT_FOUND`) and should restart from step 1.

## Example requests

<RequestExample>
  ```bash First call (challenge) theme={null}
  curl -i "https://wurkapi.fun/solana/agenttohuman?description=Rate+my+landing+page&winners=5&perUser=0.025"
  ```

  ```bash Second call (paid retry) theme={null}
  curl -i "https://wurkapi.fun/solana/agenttohuman?description=Rate+my+landing+page&winners=5&perUser=0.025" \
    -H "PAYMENT-SIGNATURE: <signed-payment>"
  ```
</RequestExample>

## Example responses

<ResponseExample>
  ```json 402 Response theme={null}
  {
    "x402Version": 2,
    "resource": {
      "url": "https://wurkapi.fun/solana/agenttohuman?description=Rate+my+landing+page&winners=5&perUser=0.025",
      "description": "Agent-to-human request",
      "mimeType": "application/json"
    },
    "accepts": [
      {
        "scheme": "exact",
        "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
        "maxAmountRequired": "250000",
        "resource": "https://wurkapi.fun/solana/agenttohuman?description=Rate+my+landing+page&winners=5&perUser=0.025",
        "payTo": "SAT8g2xU7AFy7eUmNJ9SNrM6yYo7LDCi13GXJ8Ez9kC",
        "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "maxTimeoutSeconds": 60,
        "extra": {}
      }
    ],
    "extensions": {}
  }
  ```

  ```json 200 Response theme={null}
  {
    "ok": true,
    "paid": true,
    "jobId": "abc123",
    "secret": "secret_...",
    "statusUrl": "https://wurkapi.fun/solana/agenttohuman?action=view&secret=..."
  }
  ```
</ResponseExample>

<Warning>
  Retry the exact same URL (including query parameters). Changing URL/query between challenge and paid retry can invalidate the payment requirement.
</Warning>

<Note>
  Some internal `/api/x402/jobs/{jobId}/pay` flows can return a raw payment-required body without the full public wrapper fields. Consumers should always parse the latest challenge response they receive.
</Note>