Skip to content

Commit 635be15

Browse files
stepskopstepskop
committed
docs: add agentic payments docs
1 parent 09de25b commit 635be15

File tree

1 file changed

+145
-0
lines changed

1 file changed

+145
-0
lines changed

‎sources/platform/integrations/ai/skyfire.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Agentic Payments
2+
3+
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.
4+
5+
Currently, Apify supports agentic payments through **Skyfire**, a payment network specifically designed for AI agents.
6+
7+
## What is Skyfire?
8+
9+
[Skyfire](https://skyfire.xyz/) is a payment network built specifically for AI agents, enabling autonomous transactions with digital wallets and spending controls. It provides the infrastructure necessary for agents to make payments on behalf of users, allowing truly autonomous AI-driven workflows.
10+
11+
With Skyfire integration, agents can discover available Apify Actors, execute scraping and automation tasks, and pay for services using pre-funded Skyfire tokens, all without human intervention.
12+
13+
## Using Skyfire with Apify MCP Server
14+
15+
The [Apify MCP server](https://docs.apify.com/platform/integrations/mcp) provides the simplest way for agents to access Apify's Actor library using Skyfire payments.
16+
17+
### Prerequisites
18+
19+
Before using agentic payments through MCP, you need:
20+
21+
1. **A Skyfire account** with a funded wallet - [sign up at Skyfire](https://app.skyfire.xyz/)
22+
2. **An MCP client** that supports multiple server connections, such as [OpenCode](https://opencode.ai/), Claude Desktop with MCP support, or other compatible clients
23+
3. **Both MCP servers configured**: Skyfire's MCP server and Apify's MCP server
24+
25+
### Configuration
26+
27+
Configure your MCP client to connect to both the Skyfire and Apify MCP servers. When connecting to the Apify MCP server for agentic payments, you must include the `?payment=skyfire` query parameter in the server URL. This enables the agentic payment flow and informs the agent about payment requirements.
28+
29+
#### OpenCode Configuration Example
30+
31+
If you're using [OpenCode](https://opencode.ai/), add this configuration to your `opencode.json` file (see [OpenCode configuration docs](https://opencode.ai/docs/config/) for file location on your system):
32+
33+
```json
34+
{
35+
"$schema": "https://opencode.ai/config.json",
36+
"mcp": {
37+
"skyfire": {
38+
"enabled": true,
39+
"type": "local",
40+
"command": [
41+
"npx",
42+
"mcp-remote",
43+
"https://mcp.skyfire.xyz/mcp",
44+
"--header",
45+
"skyfire-api-key: YOUR_SKYFIRE_API_KEY"
46+
]
47+
},
48+
"apify": {
49+
"enabled": true,
50+
"type": "local",
51+
"command": [
52+
"npx",
53+
"mcp-remote",
54+
"https://mcp.apify.com?payment=skyfire"
55+
]
56+
}
57+
}
58+
}
59+
```
60+
61+
Replace `YOUR_SKYFIRE_API_KEY` with your actual Skyfire buyer API key, which you can obtain from your [Skyfire dashboard](https://app.skyfire.xyz/).
62+
63+
### How It Works
64+
65+
When an agent uses the Apify MCP server with Skyfire payments, the workflow proceeds as follows. The agent searches for suitable Actors using the search tools or works with pre-loaded Actors. When attempting to run an Actor, the agent recognizes the need for a Skyfire PAY token with a minimum of five dollars. The agent automatically calls the Skyfire MCP server to create a payment token with sufficient funds.
66+
67+
The agent then calls the Actor tool with the payment token. The Apify platform validates the token and starts the Actor run. When the run completes, Apify's billing system charges the Skyfire PAY token for the actual usage cost. Any unused funds remain available in the token for future runs or are returned to your Skyfire wallet when the token expires. This means you won't lose money if the actual usage is less than the five dollar minimum.
68+
69+
Finally, the agent receives the Actor results and can retrieve additional data if needed.
70+
71+
### Pre-loading Actors
72+
73+
For more predictable workflows, you can pre-load specific Actors when connecting to the MCP server by adding them to the URL:
74+
75+
```
76+
https://mcp.apify.com?payment=skyfire&actors=actor1,actor2,actor3
77+
```
78+
79+
Replace `actor1,actor2,actor3` with the actual Actor IDs you want to make available, such as `junglee/Amazon-crawler,streamers/youtube-scraper`.
80+
81+
### Actor Discovery
82+
83+
When not pre-loading Actors, agents can discover suitable Actors dynamically using the search tools. The search automatically filters results to show only Actors that support agentic payments.
84+
85+
## Using Skyfire with Apify API
86+
87+
For direct API integration, you can use Skyfire PAY tokens to authenticate and pay for Actor runs.
88+
89+
### Authentication
90+
91+
Instead of using a traditional Apify API token, pass your Skyfire PAY token in the request header:
92+
93+
```
94+
skyfire-pay-id: YOUR_SKYFIRE_PAY_TOKEN
95+
```
96+
97+
### Running an Actor
98+
99+
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. Here's an example using the synchronous run endpoint:
100+
101+
```bash
102+
curl -X POST \
103+
'https://api.apify.com/v2/acts/ACTOR_ID/run-sync' \
104+
-H 'skyfire-pay-id: YOUR_SKYFIRE_PAY_TOKEN' \
105+
-H 'Content-Type: application/json' \
106+
-d '{
107+
"input": {
108+
"your": "input"
109+
}
110+
}'
111+
```
112+
113+
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.
114+
115+
### Retrieving Results
116+
117+
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.
118+
119+
## Limitations
120+
121+
### Supported Actors
122+
123+
Not all Actors in the Apify Store can be run using agentic payments.
124+
125+
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).
126+
127+
### Payment Requirements
128+
129+
Your Skyfire PAY token must have at least **$5** available to run Actors. However, you'll only be charged for actual usage. If an Actor run costs less than five dollars, the unused funds remain available in your token for future runs or return to your Skyfire wallet when the token expires.
130+
131+
### Unsupported Features
132+
133+
The following operations are not supported with agentic payments:
134+
135+
- Schedule creation or management
136+
- Standby run initiation
137+
- Integration setup such as webhooks to external services
138+
- Actor resurrection after the payment token has been settled
139+
140+
## Resources
141+
142+
- **[Model Context Protocol Documentation](https://docs.apify.com/platform/integrations/mcp)** - Complete guide to using the Apify MCP server
143+
- **[Skyfire Documentation](https://skyfire.xyz/)** - Official Skyfire guides and API reference
144+
- **[Apify API Reference](https://docs.apify.com/api/v2)** - Complete API documentation for direct integration
145+
- **[Actor Permissions](https://docs.apify.com/platform/actors/development/permissions)** - Understanding Actor permission levels

0 commit comments

Comments
 (0)