From 7580c8b28864c341c15b859b3dfdc46fa9b23315 Mon Sep 17 00:00:00 2001 From: stepskop Date: Mon, 8 Jun 2026 15:07:42 +0200 Subject: [PATCH 1/4] docs: improve agentic payment (x402, Skyfire) docs - x402: document accessing run/storage with the existing PAYMENT-SIGNATURE - API auth reference: mention agentic payments (x402, Skyfire) - Skyfire: discover payment requirements via X-APIFY-PAYMENT-PROTOCOL header - Drop redundant protocol header once a payment header is present (inferred) - Unify Supported Actors section across x402 and Skyfire - Document allowsAgenticUsers eligibility criteria in monetization docs --- apify-api/openapi/openapi.yaml | 10 ++++++ .../actors/publishing/monetize/index.mdx | 12 +++++++ sources/platform/integrations/ai/skyfire.md | 13 +++++++ sources/platform/integrations/ai/x402.md | 35 ++++++++++++++++--- 4 files changed, 66 insertions(+), 4 deletions(-) diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml index 5ee9352dd7..92243aa313 100644 --- a/apify-api/openapi/openapi.yaml +++ b/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 diff --git a/sources/platform/actors/publishing/monetize/index.mdx b/sources/platform/actors/publishing/monetize/index.mdx index 9109fe5917..834af31807 100644 --- a/sources/platform/actors/publishing/monetize/index.mdx +++ b/sources/platform/actors/publishing/monetize/index.mdx @@ -72,6 +72,18 @@ You can make major monetization changes to each Actor only **once per month**. A ::: +## Make your Actor eligible for agentic payments + +[Agentic payments](/platform/integrations/x402) 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, because agentic runs execute under an Apify service account rather than a user account. +- Not rely on [Standby](/platform/actors/running/standby) mode for now. Standby support is coming soon. + +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. diff --git a/sources/platform/integrations/ai/skyfire.md b/sources/platform/integrations/ai/skyfire.md index 5d41186e35..0d6107bad4 100644 --- a/sources/platform/integrations/ai/skyfire.md +++ b/sources/platform/integrations/ai/skyfire.md @@ -157,6 +157,19 @@ 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' +# → 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. diff --git a/sources/platform/integrations/ai/x402.md b/sources/platform/integrations/ai/x402.md index a5db15e3c3..faf89d5899 100644 --- a/sources/platform/integrations/ai/x402.md +++ b/sources/platform/integrations/ai/x402.md @@ -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 `. -1. Resend the request with two headers: `X-APIFY-PAYMENT-PROTOCOL: X402` and `PAYMENT-SIGNATURE: `. +1. Resend the request with the `PAYMENT-SIGNATURE: ` header. 1. The API settles the payment on-chain, runs the Actor, and returns the dataset items directly. ### Example @@ -102,7 +102,6 @@ mcpc x402 sign # Step 3: Run the Actor and get results in one call curl -s \ - -H "X-APIFY-PAYMENT-PROTOCOL: X402" \ -H "PAYMENT-SIGNATURE: " \ -H "Content-Type: application/json" \ -d '{"username": ["natgeo"], "resultsLimit": 3}' \ @@ -110,7 +109,35 @@ curl -s \ # → 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 + +x402 runs execute under an Apify service account, so you can't access them with a regular API token. Instead, 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: " \ + "https://api.apify.com/v2/actor-runs/" + +# Fetch dataset items for the run +curl -s \ + -H "PAYMENT-SIGNATURE: " \ + "https://api.apify.com/v2/datasets//items" +``` + +## Supported Actors + +Not all Actors in Apify Store can be run using agentic payments. + +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 From ff129fcec70732168a64043f6fc273de86834b8e Mon Sep 17 00:00:00 2001 From: stepskop Date: Mon, 8 Jun 2026 15:31:27 +0200 Subject: [PATCH 2/4] docs: unify Skyfire run/storage access, drop service-account wording --- .../actors/publishing/monetize/index.mdx | 2 +- sources/platform/integrations/ai/skyfire.md | 18 ++++++++++++++++-- sources/platform/integrations/ai/x402.md | 2 +- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/sources/platform/actors/publishing/monetize/index.mdx b/sources/platform/actors/publishing/monetize/index.mdx index 834af31807..d07c3b2695 100644 --- a/sources/platform/actors/publishing/monetize/index.mdx +++ b/sources/platform/actors/publishing/monetize/index.mdx @@ -79,7 +79,7 @@ You can make major monetization changes to each Actor only **once per month**. A 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, because agentic runs execute under an Apify service account rather than a user account. +- Run with [limited permissions](/platform/actors/development/permissions). Actors that request full permissions are excluded. - Not rely on [Standby](/platform/actors/running/standby) mode for now. Standby support is coming soon. Actors that meet these criteria become available to agentic users automatically - there is no separate opt-in. diff --git a/sources/platform/integrations/ai/skyfire.md b/sources/platform/integrations/ai/skyfire.md index 0d6107bad4..16e6e40d4e 100644 --- a/sources/platform/integrations/ai/skyfire.md +++ b/sources/platform/integrations/ai/skyfire.md @@ -188,9 +188,23 @@ 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 -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. +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. + +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 diff --git a/sources/platform/integrations/ai/x402.md b/sources/platform/integrations/ai/x402.md index faf89d5899..023a990960 100644 --- a/sources/platform/integrations/ai/x402.md +++ b/sources/platform/integrations/ai/x402.md @@ -113,7 +113,7 @@ You can replace `apify~instagram-post-scraper` with any [supported Actor](#suppo ### Access the run and its storages -x402 runs execute under an Apify service account, so you can't access them with a regular API token. Instead, 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. +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`. From 650734c58a93df2a45b8ebf9c7edddd4fadbe9e9 Mon Sep 17 00:00:00 2001 From: stepskop Date: Mon, 8 Jun 2026 15:44:51 +0200 Subject: [PATCH 3/4] chore: improve monetization docs --- sources/platform/actors/publishing/monetize/index.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sources/platform/actors/publishing/monetize/index.mdx b/sources/platform/actors/publishing/monetize/index.mdx index d07c3b2695..0261470f0a 100644 --- a/sources/platform/actors/publishing/monetize/index.mdx +++ b/sources/platform/actors/publishing/monetize/index.mdx @@ -80,7 +80,7 @@ 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 rely on [Standby](/platform/actors/running/standby) mode for now. Standby support is coming soon. +- Not use [Standby](/platform/actors/running/standby) mode for now. Standby support is coming soon. Actors that meet these criteria become available to agentic users automatically - there is no separate opt-in. @@ -138,4 +138,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). - From 05669dbf992d1e1a9c51bfb05adca58b51c8e5de Mon Sep 17 00:00:00 2001 From: stepskop Date: Fri, 12 Jun 2026 17:36:52 +0200 Subject: [PATCH 4/4] docs: address CR review on agentic payments docs Co-Authored-By: Claude Opus 4.8 (1M context) --- sources/platform/actors/publishing/monetize/index.mdx | 4 ++-- sources/platform/integrations/ai/skyfire.md | 10 +++++++--- sources/platform/integrations/ai/x402.md | 10 +++++++--- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/sources/platform/actors/publishing/monetize/index.mdx b/sources/platform/actors/publishing/monetize/index.mdx index 0261470f0a..cb445de453 100644 --- a/sources/platform/actors/publishing/monetize/index.mdx +++ b/sources/platform/actors/publishing/monetize/index.mdx @@ -74,13 +74,13 @@ You can make major monetization changes to each Actor only **once per month**. A ## Make your Actor eligible for agentic payments -[Agentic payments](/platform/integrations/x402) 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`. +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 soon. +- 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. diff --git a/sources/platform/integrations/ai/skyfire.md b/sources/platform/integrations/ai/skyfire.md index 16e6e40d4e..616e199e0c 100644 --- a/sources/platform/integrations/ai/skyfire.md +++ b/sources/platform/integrations/ai/skyfire.md @@ -164,7 +164,7 @@ To learn the Skyfire-specific payment details before paying, call the endpoint w ```bash curl -si \ -H 'X-APIFY-PAYMENT-PROTOCOL: SKYFIRE' \ - 'https://api.apify.com/v2/actors/ACTOR_ID/run-sync' + 'https://api.apify.com/v2/actors/ACTOR_ID/run-sync-get-dataset-items' # → HTTP 402 with the Skyfire payment requirements ``` @@ -176,7 +176,7 @@ Make a standard Actor run request to the [run Actor endpoint](https://docs.apify ```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 '{ @@ -208,7 +208,11 @@ curl -s \ ### 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). diff --git a/sources/platform/integrations/ai/x402.md b/sources/platform/integrations/ai/x402.md index 023a990960..93f94e9694 100644 --- a/sources/platform/integrations/ai/x402.md +++ b/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. ::: @@ -129,9 +129,13 @@ curl -s \ "https://api.apify.com/v2/datasets//items" ``` -## Supported Actors +### 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).