# 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|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
- **MPP** (mpp.dev): `charge` one-time payment scheme

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

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

```bash
# 1. Create / 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>     # then: npx awal auth verify <otp>
npx awal balance                # check USDC on Base; `npx awal show` opens the funding UI

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

## Paying with MPP (Tempo)

MPP's Tempo `charge` runs in **push** mode: your agent broadcasts a pathUSD
(TIP-20) transfer on Tempo and submits the transaction hash; `agi.apify.com` confirms
that transfer on-chain (read-only) and mints your token. The [mppx](https://www.npmjs.com/package/mppx)
client drives the whole 402 handshake for you.

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

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

# 3. Buy the token. mppx handles the 402, broadcasts the pathUSD 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":"..."}
```

Both rails return the same token shape. Use `token` directly against
`api.apify.com` with `Authorization: Bearer <token>`.

## Machine-readable

- https://agi.apify.com/AGENTS.md (these instructions in raw Markdown)
- https://agi.apify.com/llms.txt (the same instructions, served as plain text)