> ## 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.

# Authentication

> Payment authentication for x402 and MPP endpoints

## Authentication model

WURK endpoints in this docs set use payment-based authentication:

* **x402 routes** (`/{network}/*`) use `PAYMENT-SIGNATURE` on paid retry
* **MPP routes** (`/mpp/*`, `/mpp-solana/*`) use `Authorization: Payment ...` on paid retry

## x402 flow

<Steps>
  <Step title="First request (no payment header)">
    Call a paid endpoint like:

    ```bash theme={null}
    curl -i "https://wurkapi.fun/solana/xlikes?amount=50&url=https://x.com/user/status/123"
    ```

    Response:

    * HTTP `402`
    * `Payment-Required` (or `PAYMENT-REQUIRED`) response header
    * Payment requirements in `accepts[]`
  </Step>

  <Step title="Second request (with signed payment)">
    ```bash theme={null}
    curl -i "https://wurkapi.fun/solana/xlikes?amount=50&url=https://x.com/user/status/123" \
      -H "PAYMENT-SIGNATURE: <signed-payment>"
    ```
  </Step>
</Steps>

## MPP flow

<Steps>
  <Step title="First request (no Authorization)">
    ```bash theme={null}
    curl -i "https://wurkapi.fun/mpp/xlikes?amount=50&url=https://x.com/user/status/123"
    ```

    Response:

    * HTTP `402`
    * `WWW-Authenticate: Payment ...`
    * `application/problem+json` body (`type`, `title`, `status`, `detail`, optional `challengeId`)
  </Step>

  <Step title="Second request (Payment credential)">
    ```bash theme={null}
    curl -i "https://wurkapi.fun/mpp/xlikes?amount=50&url=https://x.com/user/status/123" \
      -H "Authorization: Payment <credential>"
    ```

    Successful responses include `Payment-Receipt`.
  </Step>
</Steps>

## Header reference

| Rail             | Initial request    | Retry request                |
| ---------------- | ------------------ | ---------------------------- |
| x402             | No payment header  | `PAYMENT-SIGNATURE: ...`     |
| MPP / MPP Solana | No `Authorization` | `Authorization: Payment ...` |

## Common payment-related statuses

| Status                     | Meaning                                          | Action                                            |
| -------------------------- | ------------------------------------------------ | ------------------------------------------------- |
| `402`                      | Payment challenge or payment verification failed | Rebuild payment using latest challenge            |
| `409`                      | Similar paid/open job already exists             | Reuse existing job reference instead of re-paying |
| `200` + `alreadyConfirmed` | Idempotent paid state                            | Treat as success                                  |

<Warning>
  Do not mix headers between rails. `PAYMENT-SIGNATURE` is x402-only, while `Authorization: Payment ...` is MPP-only.
</Warning>

## Legacy and internal notes

* Public `/{network}/*` x402 routes use `PAYMENT-SIGNATURE` (v2).
* Some legacy/internal test flows may still show `X-PAYMENT`; do not copy that header into public integrations.

## Quick questions

* **Can I reuse an old challenge?** Prefer a fresh challenge for each paid retry window.
* **Can I mix x402 and MPP headers?** No, use rail-specific headers only.
* **What if retry still returns 402?** Re-parse the latest challenge and rebuild payment proof.

## Discovery links

* x402 resource discovery: `https://wurkapi.fun/.well-known/x402`
* Tempo MPP OpenAPI: `https://wurkapi.fun/openapi.json`
* Solana MPP OpenAPI: `https://wurkapi.fun/openapi-mpp-solana.json`