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

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

`agi.apify.com`'s MPP challenge advertises a `charge` method on Tempo. It runs in
**push** mode: 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.

### 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":"..."}
```

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

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