# 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)

Rather than buying a token upfront, `agi.apify.com` can run an Actor for you directly and settle the
real cost afterward, so you never have to guess the price. This uses x402's `batch-settlement`
scheme (Base mainnet or Base Sepolia only — not Solana, not MPP): you fund a payment channel once and
reuse it; each run is capped by its own ceiling, `agi.apify.com` claims only what the run actually cost, and
the unused balance stays in the channel for your next run.

1. `POST /api-proxy/actors/{actorId}/runs?amount={usd}&currency=usd` with your Actor input as the
   JSON body and `amount` set to this run's ceiling.
2. `agi.apify.com` returns a `batch-settlement` 402 challenge. Your `batch-settlement` client signs a
   voucher when the channel's unused balance covers the ceiling, or else a deposit (first run or a
   top-up) at **3x the ceiling or more** (the client enforces this floor), and retries with
   `payment-signature`. If the client's view of the channel is stale, `agi.apify.com` answers with a
   corrective 402 that a standard client resyncs from and retries on its own — this needs a signer
   that can read the chain (an RPC-backed public client).
3. On acceptance you get back `{"receipt": "<opaque-string>"}` immediately — the run itself keeps
   going in the background.
4. Poll `GET /api-proxy/runs/{receipt}` (the result is ready within ~30 seconds after the Actor
   finishes):
   - `202` with `Retry-After`: still running.
   - `200` + your Actor's dataset: done. **This is your one and only successful read** — reading
     it revokes the run's access immediately after. If you need more than the default 10,000-item
     page, pass a bigger `limit` on this call; there's no second page.
   - `410`: you already read the result once, or waited too long (over 24 hours after completion)
     and it is no longer retrievable.
   - `404`: unknown receipt.
5. The run's real cost settles on-chain about 6 minutes after you read the result (at most 24 hours
   after it finished if you never do). Unused balance is refunded to you automatically once the
   channel has been idle for 24 hours (no new run started on it) — no action needed.

**One open run per channel.** A channel is your wallet plus your client's `salt`. Until the previous
run on a channel settles, a new run on it gets `409` with `Retry-After` (nothing is charged): retry
after that run settles, as timed in step 5. To run in parallel, pay each concurrent run from its own
channel by giving each client instance a different `salt`. A channel on which you started a timed
withdrawal accepts no new runs; use a new channel.

## 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