Skip to content

Onboarding

Register your agent's identity and prepare its session signer.

On this page

What setup establishes

  1. 01Authenticate

    You log in to Circle and select a funded wallet on the intended network.

  2. 02Verify

    Setup checks the wallet, chain and trusted MPPI deployment.

  3. 03Establish identity

    Register or adopt your ERC-8004 identity and retain a fixed session signer.

  4. 04Retain

    Keep private configuration, signer and operation evidence. Funding inference comes next.

Onboarding prepares your application. It does not deposit inference funds.

Complete the quickstart's tool installation, Circle email login and testnet funding first. In that same application folder, activate the Python environment and set MPPI_WALLET to the selected address. Circle login gives its CLI wallet access; MPPI onboarding then prepares your application's identity and session signer.

Shell · from your activated application environment
mppi-agent onboard --testnet --wallet "$MPPI_WALLET"

Onboarding is complete when the command returns complete: true. The first funded inference session comes later.

Identity and signing authority

Setup checks the selected wallet and positive USDC balance against the packaged trusted profile. It registers ERC-8004, or verifies an existing identity supplied with --agent-id ID. A supported undeployed Circle account can be activated by the intended registration; deployed code is checked before completion.

The funding wallet and fixed session signer are distinct authorities. Setup retains the signer rather than silently replacing it on rerun. When a session opens, its descriptor commits to that signer for run, voucher, reconnect and cooperative-close proofs.

Keep your configuration and evidence

Material / Purpose

.mppi/agent.json
Non-secret identity, network and configuration references.
Separate .signer file
Plaintext session credential with mode 0600 OS permissions; no wallet execution authority.
Payment and operation records
Retained provider checkpoint and original economic-operation evidence.
Circle authentication
Managed by Circle's CLI; renew access to the same wallet when needed.

Keep the entire private directory, not just the JSON file. --config PATH selects another private configuration location. Exclude custom directories from version control too. A missing or changed retained signer stops setup; deleting records is not a recovery procedure.

One built-in setup retains one provider's checkpoint. Reuse that provider/configuration pair; use separate setup directories for separate providers or networks.

Read the result before continuing

Result / Next action

Exit 0 · complete: true
Configure the client. A completed rerun retains the same identity and signer.
Exit 2 · pending
Retain the original reference and rerun the same onboarding command.
Exit 1 · failed
Read the reported failure and resolve its cause. Preserve original records.
Unknown wallet submission
Reconcile the original operation. If its Circle transaction ID was never retained, keep it unknown and resolve it with Circle before considering replacement.

A transaction hash, timeout or saved file alone does not prove a confirmed setup. Requests within a session read no chain. Opening, attachment, top-up and close use chain evidence under 60 seconds old, refreshing first when it is older, and the built-in client refreshes once a minute in the background, each refresh after the first one batch of four JSON-RPC calls; pass max_age_ms and poll_interval_ms to Client.from_config to change that. Its wallet-operation wait budget is 300 seconds; that budget does not extend a contract deadline.

If setup stops

What you see / What to check

mppi-agent: command not found
Return to this guide's folder and run source .venv/bin/activate. Check that installing mppi-agent==0.1.6 succeeded.
Circle is not authenticated
Run the same testnet email login again and select the same wallet. Keep MPPI's retained files.
Missing MPPI_PROVIDER or MPPI_MODEL
Set the two variables from step 5 in the terminal that runs Python.
Insufficient USDC
Check Arc testnet balance, the provider's rates and your chosen deposit budget.
Provider or model unavailable
Refresh the agent provider's registration and catalogue on Arc testnet. Check that the selected endpoint is reachable and still offers your model.

Select mainnet explicitly

After completing testnet setup, return to your application folder and activate its environment. Add .mppi-mainnet/ to .gitignore before onboarding. Mainnet uses real USDC and separate Circle authentication, balances, identity and MPPI records.

Shell · mainnet account login
source .venv/bin/activate
circle wallet login [email protected]

Once login succeeds, list the mainnet wallets:

Shell · select the mainnet wallet
circle wallet list --type agent --chain ARC

Replace the email before logging in and enter Circle's emailed code yourself. Copy the ARC wallet address into MPPI_MAINNET_WALLET. To deposit your chosen amount, follow Circle's funding instructions: crypto funding returns a QR code/transfer URI; fiat funding opens its onramp. Confirm the balance before continuing.

Shell · replace the address with the selected ARC wallet
export MPPI_MAINNET_WALLET="YOUR_MAINNET_WALLET"
circle wallet balance --address "$MPPI_MAINNET_WALLET" --chain ARC
mppi-agent onboard --mainnet --wallet "$MPPI_MAINNET_WALLET" \
  --config .mppi-mainnet/agent.json

Wait for complete: true, then select that configuration and network in your client. Replace the provider origin with a service running on Arc mainnet. Save this as mainnet_client.py and run python mainnet_client.py to inspect your identity; it sends no inference request:

Python · mainnet client
from pathlib import Path
from mppi_agent import Client

with Client.from_config(
    "https://YOUR_MAINNET_PROVIDER",
    config_path=Path(".mppi-mainnet/agent.json"),
    testnet=False,
    initial_session_tokens=10_000,
) as client:
    print(client.agent_id)
Onboarding | Agents | MPPI Docs