# Apify Agent General Interface (AGI)

> The front door to Apify for AI agents.

[Apify](https://apify.com/llms.txt) is the largest and most trusted marketplace of tools for AI. Thousands of **Actors** let users and agents scrape, crawl, and extract structured data from social media, e-commerce sites, search engines, maps, travel sites, or any other website, turning it into real-time web data for competitor research, lead generation, and monitoring.

`agi.apify.com` lets an AI agent buy a prepaid, spend-capped Apify API token by paying through an agentic-payment protocol (e.g. x402, MPP). You pay once; `agi.apify.com` mints a temporary Apify token with a fixed spend cap and returns it. You then call `api.apify.com` directly with that token. `agi.apify.com` is off the request path once the token is minted.

## Quick start

1. List supported protocols: `GET /protocols`.
2. Buy a token: `GET /protocols/{protocol}/prepaid-tokens?amount={usd}&currency=usd`.
3. `agi.apify.com` returns the protocol's one-time payment challenge. Pay it and retry with your signed payment credential.
4. On settlement, you receive your prepaid token.
5. Use the token directly against `api.apify.com` (`Authorization: Bearer <token>`).
6. Check the remaining balance anytime: `GET /prepaid-tokens/balance` (Bearer auth).

## Endpoints

- `GET or POST /protocols/{protocol}/prepaid-tokens?amount={usd}&currency=usd`: buy a token via `{protocol}`; the amount rides in the query (e.g. `?amount=5&currency=usd` = $5). The purchase is bodyless, so a `GET` discovery probe conveys the amount just as well as a `POST`.
- `GET /prepaid-tokens/balance`: remaining balance (Bearer auth)
- `GET /protocols`: list supported protocols

## Supported protocols

- **x402** (x402.org): `exact` one-time payment scheme, on Base or Solana
- **MPP** (mpp.dev): `charge` one-time payment scheme, on Tempo (USDC or pathUSD) or Solana (USDC or USDT)

## Terms

- **Minimum** prepaid amount: **$1**. Requests below this are rejected before settling.
- **Prepaid credit:** unused balance is non-refundable and expires with the account.
- **Temporary tokens:** the account is deleted after its TTL (currently 14 days).
- Once minted, the token works directly against `api.apify.com`; billing meters each run against the balance.

## Paying with x402 (Base or Solana)

`agi.apify.com`'s x402 challenge advertises both an EVM pair (Base) and an SVM pair (Solana) — pay whichever your wallet holds funds on. Only the `exact` scheme is accepted on either chain, never Permit2 or `upto`.

### Base (EIP-3009 USDC)

x402's `exact` scheme on EVM is a signed EIP-3009 USDC authorization: you sign it off-chain (gasless) and `agi.apify.com` settles it on-chain. The [mcpc](https://www.npmjs.com/package/@apify/mcpc) client signs the challenge.

```bash
# 1. Create and fund an x402 wallet (USDC on Base). Signing needs no gas.
mcpc x402 init               # or: mcpc x402 import <private-key>
mcpc x402                    # prints the address + USDC balance to fund

# 2. Fetch the payment challenge (the `payment-required` response header).
PR=$(curl -s -D - -o /dev/null 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=5&currency=usd' \
  | awk 'BEGIN{IGNORECASE=1}/^payment-required:/{sub(/\r$/,"");sub(/^[^:]+:[ \t]*/,"");print;exit}')

# 3. Sign it (exact scheme) -> the `payment-signature` header value.
SIG=$(mcpc x402 sign "$PR" --scheme exact --json | jq -r .paymentSignature)

# 4. Resubmit with the signature. agi.apify.com verifies, settles on-chain, and mints.
curl -s 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=5&currency=usd' \
  -H "payment-signature: $SIG"
# → {"token":"apify_api_...","remainingBalanceUsd":5,"expiresAt":"..."}
```

Or use [awal](https://www.npmjs.com/package/awal), Coinbase's wallet CLI, which signs, settles, and retries the 402 for you in a single command:

```bash
# 1. Sign in and fund the wallet with USDC on Base (one-time).
npx awal auth login <email>    # sign in
npx awal auth verify <otp>     # confirm the one-time code
npx awal show                  # open the funding UI to add USDC on Base
# Alternatively, use the npx awal address command to get the funding address directly (no GUI).
npx awal balance               # check your USDC balance

# 2. Buy the token — awal runs the 402 handshake + on-chain settlement, then prints it.
#    --max-amount caps the spend in USDC atomic units (5000000 = $5.00).
npx awal x402 pay 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=5&currency=usd' --max-amount 5000000
# → {"token":"apify_api_...","remainingBalanceUsd":5,"expiresAt":"..."}
```

### Solana (USDC/USDT)

x402's `exact` scheme on Solana is a client-signed, partially-signed transaction (no gas fee for you — the facilitator co-signs as fee payer and broadcasts). Use an x402-aware Solana client from the [x402 ecosystem](https://docs.x402.org/core-concepts/client-server) to build, sign, and resubmit against the same `/protocols/x402/prepaid-tokens` endpoint; `agi.apify.com` accepts whichever of the two `accepts` entries (Base or Solana) your client signs against.

Or use [pay.sh](https://pay.sh), Solana Foundation's payments CLI, which drives the whole handshake for you:

```bash
# 1. Install pay.sh and fund a Solana wallet with USDC or USDT.
npm install -g @solana/pay
pay setup                      # Touch ID / Windows Hello / GNOME Keyring
pay whoami                     # prints the address to fund

# 2. Buy the token — pay.sh runs the 402 handshake, signs, and retries for you.
pay --mainnet --x402 curl 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=5&currency=usd'
# → {"token":"apify_api_...","remainingBalanceUsd":5,"expiresAt":"..."}
```

## Paying with MPP (Tempo or Solana)

`agi.apify.com`'s MPP challenge advertises a `charge` method on Tempo and on Solana, in either **push** or **pull** mode:

- **push**: your agent broadcasts the stablecoin transfer itself and submits the transaction reference; `agi.apify.com` confirms it on-chain (read-only) and mints your token.
- **pull**: your agent signs the transfer but does not broadcast it; `agi.apify.com` broadcasts the signed transaction and confirms it, still at your agent's expense (no fee sponsorship). Use this if your client can sign but can't broadcast.

### Tempo (pathUSD/TIP-20)

The [mppx](https://www.npmjs.com/package/mppx) client drives the whole 402 handshake for you.

Accepted currencies: **USDC or pathUSD**. The 402 advertises one challenge per currency — answer whichever you hold.

```bash
# 1. Install the mppx client.
npm i -g mppx

# 2. Create a Tempo account (mppx manages the wallet locally) and fund it with
#    USDC or pathUSD on Tempo.
mppx account create
mppx account view            # prints the address to fund

# 3. Buy the token. mppx handles the 402, broadcasts the transfer, and
#    retries automatically, then prints the minted token.
mppx 'https://agi.apify.com/protocols/mpp/prepaid-tokens?amount=5&currency=usd'
# → {"token":"apify_api_...","remainingBalanceUsd":5,"expiresAt":"..."}
```

### Solana (USDC/USDT)

Use the [mppx](https://www.npmjs.com/package/mppx) client with [`@solana/mpp`](https://www.npmjs.com/package/@solana/mpp). `signer` is a `@solana/kit` `TransactionSigner`; `broadcast: false` is **pull**, `true` is **push**. Either way the wallet needs a little SOL for the network fee, and `agi.apify.com` does not sponsor it.

```js
import { Mppx } from 'mppx/client';
import { solana } from '@solana/mpp/client';

const mppx = Mppx.create({
    methods: [solana.charge({ signer, broadcast: true })],
    polyfill: false, // keep the global fetch untouched
});
const res = await mppx.fetch('https://agi.apify.com/protocols/mpp/prepaid-tokens?amount=5&currency=usd');
// → {"token":"apify_api_...","remainingBalanceUsd":5,"expiresAt":"..."}
```

Or use [pay.sh](https://pay.sh) (install and fund it as in the x402 Solana section above), which signs a pull credential and retries the 402 for you:

```bash
pay --mainnet --mpp curl 'https://agi.apify.com/protocols/mpp/prepaid-tokens?amount=5&currency=usd'
# → {"token":"apify_api_...","remainingBalanceUsd":5,"expiresAt":"..."}
```

Accepted currencies: **USDC or USDT** (the mint is the challenge's `currency`). The client answers the first challenge it can pay, in the server's order (USDC first); a wallet that holds only USDT should pass `orderChallenges` to `Mppx.create` to prefer the USDT one. Prefer **push** when your client can broadcast: an underfunded wallet then fails locally and nothing reaches `agi.apify.com`.

Use `token` directly against `api.apify.com` with `Authorization: Bearer <token>`. See the [Apify API reference](https://docs.apify.com/api/v2) for the available endpoints ([OpenAPI spec](https://docs.apify.com/api/openapi.json)).

## Proxied Actor runs (x402 batch-settlement, Base only)

`agi.apify.com` can run an Actor for you and bill the real cost afterward, with no price guessing. It uses x402's `batch-settlement` scheme (Base mainnet or Base Sepolia only, not Solana or MPP): fund a payment channel once and reuse it. Each run is capped by its ceiling (`amount`), only the actual cost is claimed, and the rest stays in the channel.

**Limits**
- **A limited number of open runs per channel.** A channel is your wallet plus your client's `salt`. A run stays open until its billing settles, about 6 minutes after you fetch its result (up to 24 hours if you never do). The service caps the open runs per channel (1 by default); a request over the cap gets `409` with `Retry-After`, and nothing is charged. Do not send requests on one channel simultaneously: wait for each response before the next. For more parallel runs, use a different `salt` per run (each channel needs its own deposit) or buy a prepaid token above.
- **Errors:** `400` for an invalid `amount`, `currency`, `actorId` or `memory`; `429` when the channel's recent runs keep failing to start (nothing is charged; `Retry-After` is about 10 minutes).
- **Minimum charge: $0.001 per run** (the facilitator's minimum, 1000 units of USDC), never above the ceiling. A run that used nothing costs nothing.

1. `POST /api-proxy/actors/{actorId}/runs?amount={usd}&currency=usd` with the Actor input as the JSON body. `amount` is this run's ceiling.
2. You get a `batch-settlement` 402 challenge. Your client signs a voucher when the channel's unused balance covers the ceiling, otherwise a deposit of **3x the ceiling or more** (the client enforces this), and retries with `payment-signature`. If its view of the channel is stale, a corrective 402 comes back that a standard client fixes and retries by itself (needs a signer that can read the chain).
3. You get `{"receipt": "<opaque-string>"}` at once; the run continues in the background.
4. Poll `GET /api-proxy/runs/{receipt}`:
   - `202` with `Retry-After`: still running.
   - `200` with the whole dataset (`limit` and `offset` are ignored; `format` and `fields` work). **This is your one successful read**: the run's access is then revoked. A read that breaks half-way is not consumed.
   - `410`: already read, or more than 24 hours since completion. `404`: unknown receipt.
5. The real cost settles on-chain about 6 minutes after you read the result. Unused balance is refunded after 24 hours idle. A channel with a timed withdrawal started takes no new runs; use a new one.

## Using the token with the Apify MCP server

The minted token is a normal Apify API token, so it also works as the Bearer credential for the [Apify MCP server](https://mcp.apify.com), which provides tools to search and call Apify's Actors. Skip the OAuth sign-in and pass the prepaid token in the `Authorization` header:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com",
      "headers": { "Authorization": "Bearer apify_api_..." }
    }
  }
}
```

Or connect from the command line with [mcpc](https://www.npmjs.com/package/@apify/mcpc):

```bash
mcpc connect mcp.apify.com @apify --header "Authorization: Bearer apify_api_..."
mcpc @apify tools-list
```

Every tool call is metered against the token's prepaid balance, just like a direct `api.apify.com` call.

## Machine-readable

These same instructions are available as Markdown at https://agi.apify.com/llms.txt and https://agi.apify.com/AGENTS.md