docs: add direct API quickstart and improve x402 docs page (#2392)

## Summary

- Adds a new **"Use x402 with the Apify API directly"** section with
step-by-step payment flow and curl example using
`run-sync-get-dataset-items`
- Restructures the page for clarity: shared prerequisites/wallet setup
at the top, parallel "How it works" + "Example" subsections for both MCP
and direct API paths
- Moves pricing/refund details into a single shared section to avoid
duplication
- Tightens intro and removes AI-sloppy filler phrases flagged in
readability review
- Adds "Supported Actors" info admonition (Pay Per Event only, no
Standby) at page top
- Adds "Agent autonomy" tip suggesting users provide this page as
context to their AI agent
- Fixes style issues: replaces em dashes with hyphens, removes incorrect
bold emphasis

---------

Co-authored-by: Marcel Rebro <marcel.rebro@apify.com>

Author: MQ37

sources/platform/integrations/ai/x402.md

@@ -1,74 +1,129 @@
 ---
 title: Agentic payments with x402 protocol
 sidebar_label: x402
-description: Use the x402 protocol to enable AI agents to autonomously pay for Apify Actor runs using USDC on the Base blockchain.
+description: Use the x402 protocol to enable AI agents to autonomously pay for Apify Actor runs using USDC on the Base blockchain - no Apify account required.
 sidebar_position: 19
 slug: /integrations/x402
 ---
 
-Agentic payments enable AI agents to autonomously run Apify Actors using third-party payment providers, without requiring traditional Apify user accounts. This allows agents to discover, execute, and pay for web scraping and automation tasks independently.
-
-Apify supports agentic payments through the [x402 protocol](https://www.x402.org/), an open standard for internet-native payments.
+With the [x402 protocol](https://www.x402.org/), AI agents can run Apify Actors and pay with USDC on the [Base](https://www.base.org/) blockchain - no Apify account needed.
 
 :::caution Experimental feature
 
-Agentic payments are an experimental feature and may change significantly as payment protocols and AI technologies evolve.
+Agentic payments are experimental and may change as payment protocols evolve. Only Actors with the [Pay Per Event](/platform/actors/publishing/monetize/pay-per-event) pricing model are supported. [Standby](/platform/actors/running/standby) Actors are not supported.
 
 :::
 
 ## What is x402
 
-The [x402 protocol](https://www.x402.org/) is an open standard for internet-native payments. It enables direct on-chain payments using USDC on the [Base](https://www.base.org/) blockchain.
+The [x402 protocol](https://www.x402.org/) is an open standard for on-chain payments over HTTP. It uses [USDC](https://www.circle.com/usdc), a stablecoin pegged to the US dollar, on the [Base](https://www.base.org/) blockchain.
 
-The Apify MCP server implements an MCP extension of this protocol to support agentic payments. The client automatically detects payment requirements in the tool's metadata and signs a USDC payment on the Base blockchain (mainnet). This payment is included with the tool call - no human intervention needed.
+When a server requires payment, it responds with HTTP `402` and tells the client what payment formats it accepts. The client signs a USDC transfer off-chain (locally, without touching the blockchain) and resends the request with the signature attached. The server settles (finalizes) the payment on-chain (on the blockchain) and processes the request.
 
-## Use x402 with Apify MCP server
+## Prerequisites
+
+- [`mcpc` CLI](https://github.com/apify/mcp-cli) installed (`npm install -g @apify/mcpc`) - manages your wallet and signs payments.
+- A wallet funded with USDC on [Base](https://www.base.org/) mainnet.
 
-The [Apify MCP server](/platform/integrations/mcp) provides the simplest way for agents to access Apify's Actor library using x402 payments.
+### Wallet setup
 
-### Prerequisites
+Use the `mcpc` CLI to create or import a wallet:
 
-- _`mcpc` CLI_ - Install the [`mcpc` CLI](https://github.com/apify/mcp-cli) (`npm install -g @apify/mcpc`), the Universal MCP command-line client.
-- _USDC on Base_ - A wallet funded with USDC on the [Base](https://www.base.org/) mainnet blockchain.
+```bash
+# Create a new wallet (generates a random private key)
+mcpc x402 init
 
-### Setup
+# Or import an existing wallet from a private key
+mcpc x402 import <private-key>
 
-Set up a local wallet and connect to the Apify MCP server with x402 payment support.
+# Verify your wallet address
+mcpc x402 info
+```
 
-1. Create or import a wallet:
+Fund the displayed wallet address with USDC on Base mainnet.
 
-    ```bash
-    # Create a new wallet (generates a random private key)
-    mcpc x402 init
+## Use x402 with Apify MCP server
 
-    # Or import an existing wallet from a private key
-    mcpc x402 import <private-key>
+The [Apify MCP server](/platform/integrations/mcp) is the recommended way to get started. `mcpc` handles payment signing and retries automatically.
 
-    # Verify your wallet address
-    mcpc x402 info
-    ```
+### How it works
 
-1. Fund the wallet with USDC on Base mainnet.
+1. The MCP server advertises payment requirements in each paid tool's metadata.
+1. When `mcpc` calls a paid tool, it signs a USDC payment using your wallet and includes it in the request.
+1. The server verifies and settles the payment on-chain, then runs the tool and returns the result.
+1. If you call a tool without a payment, the server responds that payment is required and `mcpc` signs and retries automatically.
 
-1. Connect to the Apify MCP server with x402 payment mode enabled. Add the `?payment=x402` query parameter to the server URL and pass the `--x402` flag to `mcpc`:
+### Example
 
-    ```bash
-    mcpc connect "mcp.apify.com?payment=x402" @apify --x402
-    ```
+:::tip Agent autonomy
 
-1. Call tools as usual. Payments are handled automatically:
+Provide this page (or the example below) as context to your AI agent. The agent can then connect to the Apify MCP server and pay for tools via x402 autonomously - no human in the loop.
 
-    ```bash
-    mcpc @apify tools-call call-actor actor:="apify/rag-web-browser" input:='{"query": "latest AI news"}'
-    ```
+:::
+
+```bash
+# Connect to the Apify MCP server with x402 enabled
+mcpc connect "mcp.apify.com?payment=x402" @apify --x402
+
+# Call a paid tool - payment is handled automatically
+mcpc @apify tools-call call-actor actor:="apify/instagram-post-scraper" input:='{"username": ["natgeo"], "resultsLimit": 3}'
+```
+
+## Use x402 with the Apify API directly
+
+You can also send x402 payments directly against the Apify REST API. This works with any HTTP client or x402-compatible wallet.
 
 ### How it works
 
-When x402 payment mode is enabled, the agent handles the full payment flow autonomously:
+1. Call the Apify API with the header `X-APIFY-PAYMENT-PROTOCOL: X402` and no payment signature.
+1. The API returns HTTP `402` with a `PAYMENT-REQUIRED` header - base64-encoded JSON listing accepted payment formats.
+1. Sign the payment using `mcpc x402 sign <PAYMENT-REQUIRED header value>`.
+1. Resend the request with two headers: `X-APIFY-PAYMENT-PROTOCOL: X402` and `PAYMENT-SIGNATURE: <signed payload>`.
+1. The API settles the payment on-chain, runs the Actor, and returns the dataset items directly.
+
+### Example
+
+:::caution Actor name format
+
+When using the API, replace the `/` in the Actor name with `~` (for example, `apify/instagram-post-scraper` becomes `apify~instagram-post-scraper`).
+
+:::
+
+```bash
+# Step 1: Discover payment requirements
+curl -si \
+  -H "X-APIFY-PAYMENT-PROTOCOL: X402" \
+  "https://api.apify.com/v2/acts/apify~instagram-post-scraper/run-sync-get-dataset-items"
+# → HTTP 402 + PAYMENT-REQUIRED header value
+
+# Step 2: Sign the payment with mcpc
+mcpc x402 sign <PAYMENT-REQUIRED header value>
+# → outputs your base64 PAYMENT-SIGNATURE
+
+# Step 3: Run the Actor and get results in one call
+curl -s \
+  -H "X-APIFY-PAYMENT-PROTOCOL: X402" \
+  -H "PAYMENT-SIGNATURE: <base64-signed-payload>" \
+  -H "Content-Type: application/json" \
+  -d '{"username": ["natgeo"], "resultsLimit": 3}' \
+  "https://api.apify.com/v2/acts/apify~instagram-post-scraper/run-sync-get-dataset-items"
+# → JSON array with the scraped Instagram posts
+```
+
+You can replace `apify~instagram-post-scraper` with any supported Actor from [Apify Store](https://apify.com/store).
+
+## Pricing and refunds
+
+Both paths (MCP server and direct API) share the same pricing model:
+
+- Minimum transaction: $1 in USDC.
+- The payment is tracked as a prepaid balance. Subsequent calls draw from it without new on-chain transactions.
+- When using the MCP server, `mcpc` signs a new payment automatically when the balance runs out.
+- After 60 minutes of inactivity (no running Actors), any remaining balance is refunded on-chain to your wallet, minus a small [gas fee (network cost)](https://docs.base.org/base-chain/network-information/network-fees) charged by the Base network to process the transaction.
 
-1. The Apify MCP server advertises payment requirements in each paid tool's metadata.
-1. When `mcpc` calls a paid tool, it automatically signs a USDC payment using your local wallet and includes it in the request.
-1. The server verifies and settles the payment on-chain, then executes the tool and returns the result.
-1. If a tool is called without a payment, the server responds that payment is required and `mcpc` signs and retries automatically.
+## Next steps
 
-The Apify MCP server requires a minimum transaction of $1.00. The server tracks the payment as a balance. Subsequent tool calls draw from this balance without requiring a new on-chain transaction. When the balance runs out, `mcpc` automatically signs a new payment to top it up. After a period of inactivity, the server refunds any remaining unused balance to the client's wallet address on the Base blockchain.
+- Browse [Apify Store](https://apify.com/store) for supported Actors to use with x402.
+- Learn more about [Pay Per Event](/platform/actors/publishing/monetize/pay-per-event) pricing for Actors.
+- Set up the [Apify MCP server](/platform/integrations/mcp) for automated tool discovery and payment handling.
+- Read the [x402 protocol specification](https://www.x402.org/) for technical details on the payment standard.