Skip to content

Quickstart

Create a Circle account, give your agent a wallet and make its first paid inference request on Arc testnet.

On this page

Before you begin

This guide uses Python and Circle Agent Wallet, MPPI's built-in wallet integration. You need your own email inbox and a macOS/Linux terminal. After wallet setup, choose an agent provider from the ERC-8004 registry on Arc testnet.

1. Install

Install Node.js 20.18.2+ and uv using the links below. Open a new terminal, then create your project and install the SDK and Circle CLI:

Shell
mkdir mppi-agent-quickstart
cd mppi-agent-quickstart
uv venv --python 3.12
source .venv/bin/activate
uv pip install 'mppi-agent==0.1.6'
npm install -g @circle-fin/cli@1.1.4
mppi-agent --help

MPPI's Circle adapter accepts only this verified CLI version and refuses any other before anything is sent; other wallets are not affected.

The help output should list onboard. Keep using this folder and terminal. In a new terminal, return here and activate .venv again.

2. Create your Circle account

Your Circle Agent Wallet account is created in the terminal on first login. Replace the email below with your own:

Shell
circle wallet login [email protected] --testnet

Read and accept Circle's terms, then enter the code sent to your email. Circle creates your wallets automatically. Enter the code yourself; keep your inbox out of your agent's access.

Shell · after login succeeds
circle wallet list --type agent --chain ARC-TESTNET

Copy the Arc testnet wallet address into this variable, replacing the placeholder:

Shell
export MPPI_WALLET="YOUR_WALLET_ADDRESS"

3. Add testnet USDC

Shell
circle wallet fund --address "$MPPI_WALLET" --chain ARC-TESTNET
circle wallet balance --address "$MPPI_WALLET" --chain ARC-TESTNET

The first command requests faucet funds. Continue when the second shows a positive USDC balance on Arc testnet.

4. Set up MPPI

Add these entries to .gitignore in your project before onboarding:

.gitignore
.venv/
.mppi/
Shell
mppi-agent onboard --testnet --wallet "$MPPI_WALLET"

MPPI registers your identity and saves a separate session signing credential under .mppi/. No inference deposit is made yet. Continue when the result says complete: true.

Keep .mppi/ private and retain it across restarts. If setup returns exit code 2, rerun this same command to check the original operation. For exit code 1, resolve the reported error; keep the records.

5. Choose an agent provider

Find an agent provider through the ERC-8004 registry. Its registration document identifies the MPPI service's HTTPS origin; its published catalogue lists model IDs and prices. Use the Arc testnet registry for this guide.

For this example, copy that origin and your chosen model ID below. The final command reads the published model details. Review the model and its current prices before continuing.

Shell
export MPPI_PROVIDER="https://YOUR_PROVIDER"
export MPPI_MODEL="YOUR_PROVIDER/MODEL"
curl --fail --show-error "$MPPI_PROVIDER/models"

You can also pass the registered agent provider ID as an integer to Client.from_config in step 6. The SDK resolves the origin and checks its models and prices against the registry.

6. Make a request

Save this as request.py in your project. initial_session_tokens=10_000 chooses a deposit using the provider's highest applicable token rate, rounded up. Review that budget first: it is not an output-token limit.

Python · request.py
import os
from mppi_agent import Client

with Client.from_config(
    os.environ["MPPI_PROVIDER"],
    testnet=True,
    initial_session_tokens=10_000,
) as client:
    response = client.chat.completions.create(
        model=os.environ["MPPI_MODEL"],
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(response.decode("utf-8"))
    for session in client.sessions.list().sessions:
        print("Session:", session.session_id.hex(), session.status)
Shell
python request.py

You should see response JSON, then the session ID and status. The SDK has funded the session and handled its payment messages.

If the request times out or disconnects, inspect the original session before trying again. Missing output does not mean no work ran.

Finish or keep building

The session stays funded after the script exits. Reuse it for more requests, or follow the close procedure below to settle it and return unused funds to your wallet.

Quickstart | Agents | MPPI Docs