# Apify AGentic Interface (AGI)

> The front door for AI agents on Apify.

`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: `POST /protocols/{protocol}/prepaid-tokens` with the desired
   amount in 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 remaining balance anytime: `GET /prepaid-tokens/balance` (Bearer auth).

## Endpoints

- `POST /protocols/{protocol}/prepaid-tokens` — buy a token via `{protocol}`
- `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 USD**. 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 -X POST https://agi.apify.com/protocols/x402/prepaid-tokens \
  -H 'content-type: application/json' -d '{"amountUsd":5}' \
  | 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 -X POST https://agi.apify.com/protocols/x402/prepaid-tokens \
  -H 'content-type: application/json' -H "payment-signature: $SIG" \
  -d '{"amountUsd":5}'
# → {"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 -J '{"amountUsd":5}'
# → {"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

- `/AGENTS.md` — these instructions in raw markdown
- `/llms.txt` — the same instructions, served as plain text