docs(agentic-payments): improve docs about x402 and Skyfire payment providers

apify-api/openapi/openapi.yaml

@@ -59,6 +59,16 @@ info:
     For more information, see our
     [integrations](https://docs.apify.com/platform/integrations) documentation.
 
+    ### Agentic payments
+
+    AI agents can authenticate and pay for Actor runs without an Apify account
+    using agentic payments. Instead of an API token, the request carries a
+    payment credential that both authorizes and pays for the call. Apify supports
+    the [x402 protocol](https://docs.apify.com/platform/integrations/x402)
+    (`PAYMENT-SIGNATURE` header) and
+    [Skyfire](https://docs.apify.com/platform/integrations/skyfire)
+    (`skyfire-pay-id` header).
+
     ## Basic usage
     <span id="/introduction/basic-usage"></span>
 

sources/platform/actors/publishing/monetize/index.mdx

@@ -63,6 +63,37 @@ You can make major monetization changes to each Actor only **once per month**. A
 
 :::
 
+## Make your Actor eligible for agentic payments
+
+Agentic payments let AI agents discover, run, and pay for your Actor without an Apify account, using protocols such as [x402](/platform/integrations/x402) and [Skyfire](/platform/integrations/skyfire). Eligible Actors are flagged with `allowsAgenticUsers=true` and surface in agentic discovery, for example when [searching the store via API](https://docs.apify.com/api/v2#/reference/store/store-actors-collection/get-list-of-actors-in-store) with `allowsAgenticUsers=true`.
+
+To be eligible for agentic payments, your Actor must:
+
+- Use the [pay per event](/platform/actors/publishing/monetize/pay-per-event) pricing model. Rental and pay-per-usage Actors are not supported.
+- Run with [limited permissions](/platform/actors/development/permissions). Actors that request full permissions are excluded.
+- Not use [Standby](/platform/actors/running/standby) mode for now. Standby support is coming later.
+
+Actors that meet these criteria become available to agentic users automatically - there is no separate opt-in.
+
+## Monthly payouts and analytics
+
+Payout invoices are automatically generated on the 11th of each month, summarizing the profits from all your Actors for the previous month.
+In accordance with the [Terms & Conditions](/legal/store-publishing-terms-and-conditions), only funds from legitimate users who have already paid are included in the payout invoice.
+
+:::note How negative profits are handled
+
+If your PPE Actor's price doesn't cover its monthly platform usage costs, it will have a negative profit. When this occurs, we automatically set that Actor's profit to $0 for the month. This ensures a single Actor's loss never reduces your total payout.
+
+:::
+
+You have 3 days to review your payout invoice in the **Development >Insights > Payout** section. During this period, you can either approve the invoice or request a revision, which we will process promptly.
+If no action is taken, the payout will be automatically approved on the 14th, with funds disbursed shortly after. Payouts require meeting minimum thresholds of either:
+
+- $20 for PayPal
+- $100 for other payout methods
+
+If the monthly profit does not meet these thresholds, as per the [Terms & Conditions](/legal/store-publishing-terms-and-conditions), the funds will roll over to the next month until the threshold is reached.
+
 ## Handle free users
 
 When monetizing your Actor, you might want to limit features or usage for users on the Apify free plan. If you choose to do this, you _must_ handle it transparently:
@@ -98,4 +129,3 @@ Create search-engine-optimized descriptions and README files to improve search e
 Remember to tag Apify in your social media posts for additional exposure. Effective promotion can significantly impact your Actor's success, differentiating between those with many paid users and those with few to none.
 
 Learn more about promoting your Actor with  [Apify's marketing checklist](/academy/actor-marketing-playbook/promote-your-actor/checklist).
-

sources/platform/integrations/ai/skyfire.md

@@ -157,13 +157,26 @@ Instead of using a traditional Apify API token, pass your Skyfire PAY token in t
 skyfire-pay-id: YOUR_SKYFIRE_PAY_TOKEN
 ```
 
+### Discover payment requirements
+
+To learn the Skyfire-specific payment details before paying, call the endpoint without a token and add the `X-APIFY-PAYMENT-PROTOCOL: SKYFIRE` header. The API responds with HTTP `402` and the Skyfire payment requirements, which you use to create a PAY token.
+
+```bash
+curl -si \
+  -H 'X-APIFY-PAYMENT-PROTOCOL: SKYFIRE' \
+  'https://api.apify.com/v2/actors/ACTOR_ID/run-sync-get-dataset-items'
+# → HTTP 402 with the Skyfire payment requirements
+```
+
+Once you send the `skyfire-pay-id` header, the protocol is inferred from it, so you no longer need to include `X-APIFY-PAYMENT-PROTOCOL`.
+
 ### Run an Actor
 
 Make a standard Actor run request to the [run Actor endpoint](https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor), but include the Skyfire PAY token in the header.
 
 ```bash title="Example of using the synchronous run endpoint"
 curl -X POST \
-  'https://api.apify.com/v2/actors/ACTOR_ID/run-sync' \
+  'https://api.apify.com/v2/actors/ACTOR_ID/run-sync-get-dataset-items' \
   -H 'skyfire-pay-id: YOUR_SKYFIRE_PAY_TOKEN' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -175,13 +188,31 @@ curl -X POST \
 
 You can also use the asynchronous [run Actor endpoint](https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor) if you don't need to wait for results immediately.
 
-### Retrieving results
+### Access the run and its storages
+
+To access a run and its storages, reuse the same `skyfire-pay-id` header as authentication. As long as you send the token that paid for the run, you can call the [run](https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages/get-run), [dataset](https://docs.apify.com/api/v2#/reference/datasets), and [key-value store](https://docs.apify.com/api/v2#/reference/key-value-stores) endpoints for that run and its default storages.
 
-After your Actor run completes, you can retrieve results using the [dataset endpoints](https://docs.apify.com/api/v2#/reference/datasets) or [key-value store endpoints](https://docs.apify.com/api/v2#/reference/key-value-stores). Include the same `skyfire-pay-id` header to authenticate these requests.
+This is useful when you start a run asynchronously with the [Run Actor](https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor) endpoint and then poll its status or fetch results separately.
+
+```bash
+# Get run status - authenticate with the same Skyfire PAY token
+curl -s \
+  -H 'skyfire-pay-id: YOUR_SKYFIRE_PAY_TOKEN' \
+  'https://api.apify.com/v2/actor-runs/RUN_ID'
+
+# Fetch dataset items for the run
+curl -s \
+  -H 'skyfire-pay-id: YOUR_SKYFIRE_PAY_TOKEN' \
+  'https://api.apify.com/v2/datasets/DATASET_ID/items'
+```
 
 ### Supported Actors
 
-Not all Actors in Apify Store can be run using agentic payments.
+Not all Actors in Apify Store can be run using agentic payments. To be eligible, an Actor must:
+
+- Use the [pay per event](/platform/actors/publishing/monetize/pay-per-event) pricing model. Rental and pay-per-usage Actors are not supported.
+- Run with [limited permissions](/platform/actors/development/permissions). Actors that request full permissions are excluded.
+- Not use [Standby](/platform/actors/running/standby) mode for now. Standby support is coming later.
 
 Apify maintains a curated list of Actors approved for agentic payments. To check if an Actor supports agentic payments, use the `allowsAgenticUsers=true` query parameter when [searching the store via API](https://docs.apify.com/api/v2#/reference/store/store-actors-collection/get-list-of-actors-in-store).
 

sources/platform/integrations/ai/x402.md

@@ -10,7 +10,7 @@ With the [x402 protocol](https://www.x402.org/), AI agents can run Apify Actors
 
 :::caution Experimental feature
 
-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.
+Agentic payments are experimental and may change as payment protocols evolve.
 
 :::
 
@@ -75,10 +75,10 @@ You can also send x402 payments directly against the Apify REST API. This works
 
 ### How it works
 
-1. Call the Apify API with the header `X-APIFY-PAYMENT-PROTOCOL: X402` and no payment signature.
+1. Call the Apify API with 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. Resend the request with the `PAYMENT-SIGNATURE: <signed payload>` header.
 1. The API settles the payment on-chain, runs the Actor, and returns the dataset items directly.
 
 :::note Reuse the same signature
@@ -108,15 +108,46 @@ mcpc x402 sign <PAYMENT-REQUIRED header value>
 
 # 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/actors/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).
+You can replace `apify~instagram-post-scraper` with any [supported Actor](#supported-actors) from [Apify Store](https://apify.com/store).
+
+### Access the run and its storages
+
+To access a run and its storages, reuse the same `PAYMENT-SIGNATURE` header as authentication. As long as you send the signature that paid for the run, you can call the [run](https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages/get-run), [dataset](https://docs.apify.com/api/v2#/reference/datasets), and [key-value store](https://docs.apify.com/api/v2#/reference/key-value-stores) endpoints for that run and its default storages.
+
+This is useful when you start a run asynchronously with the [Run Actor](https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor) endpoint and then poll its status or fetch results separately, instead of using `run-sync-get-dataset-items`.
+
+```bash
+# Get run status - authenticate with the same PAYMENT-SIGNATURE
+curl -s \
+  -H "PAYMENT-SIGNATURE: <base64-signed-payload>" \
+  "https://api.apify.com/v2/actor-runs/<runId>"
+
+# Fetch dataset items for the run
+curl -s \
+  -H "PAYMENT-SIGNATURE: <base64-signed-payload>" \
+  "https://api.apify.com/v2/datasets/<datasetId>/items"
+```
+
+### Supported Actors
+
+Not all Actors in Apify Store can be run using agentic payments. To be eligible, an Actor must:
+
+- Use the [pay per event](/platform/actors/publishing/monetize/pay-per-event) pricing model. Rental and pay-per-usage Actors are not supported.
+- Run with [limited permissions](/platform/actors/development/permissions). Actors that request full permissions are excluded.
+- Not use [Standby](/platform/actors/running/standby) mode for now. Standby support is coming later.
+
+Apify maintains a curated list of Actors approved for agentic payments. To check if an Actor supports agentic payments, use the `allowsAgenticUsers=true` query parameter when [searching the store via API](https://docs.apify.com/api/v2#/reference/store/store-actors-collection/get-list-of-actors-in-store).
+
+```text
+https://api.apify.com/v2/store?allowsAgenticUsers=true
+```
 
 ## Pricing and refunds