Skip to content

Wallets and accounts

Give your agent a wallet to pay for inference. Start with Circle or connect another wallet provider through your own adapter.

On this page

Choose your wallet provider

Circle Agent Wallet is the quickest path through MPPI's built-in setup. Another wallet provider works through an explicit integration. MPPI does not require a Circle account for that path.

Why Circle Agent Wallet

  • Built-in MPPI adapter: use the documented setup without writing wallet integration code.
  • Email account setup: Circle creates your wallets after you sign in.
  • MPC key management: Circle uses two key shares and does not expose them to the agent.
  • Sponsored transaction gas: subject to Circle's caps and fair-use rules. You still fund inference with USDC.

Circle is a wallet service, so your application depends on its availability and authentication. Keep login access current. MPPI's separate session signing credential still needs private, durable storage.

Create your Circle account

First install Node.js 20.18.2+ and Circle CLI. Your Agent Wallet account is created during email login in the terminal; this setup does not use a Circle Console API key.

Shell
npm install -g @circle-fin/cli@1.1.4

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

Replace the email with your own. Read and accept Circle's terms, then enter the emailed code yourself. Keep the inbox and code out of your agent's access.

Shell
circle wallet login [email protected] --testnet

After login succeeds, select your wallet on Arc testnet:

Shell
circle wallet list --type agent --chain ARC-TESTNET

Copy the address, then follow the quickstart to add testnet USDC and register with MPPI.

Use another wallet provider

Use this path when you already have a wallet service and want to keep it. You supply the adapter; MPPI supplies the payment protocol. An Arc address alone is not enough, and Client.from_config remains the Circle setup path.

1. Implement the wallet interface. Install mppi-agent==0.1.6 in a Python 3.12+ environment. Wrap your wallet service with these four members:

FundingWallet member / Your adapter supplies

address
The selected funding wallet as 20 address bytes.
sign_funding_authorization(authorization)
Sign the exact USDC authorization and return signature bytes. Use the supplied token domain, amount, recipient, validity window and nonce.
execute(call, *, operation_ref)
Submit the exact call on the specified chain. Retain its intent and operation reference before submission; return an OperationResult with real evidence.
reconcile(*, operation_ref)
Read the original operation's status and evidence. Never send a replacement transaction from this method.

Funding needs your agent's ERC-8004 ID: pass agent_id to Client. Before an opening, the SDK checks that the registry binds that ID to address and that USDC would accept the signature; it pins no wallet implementation or version. If your wallet service creates the signature when it executes, set signs_at_execute = True on your adapter: the SDK then checks only the binding, passes your placeholder to execute, and USDC checks the real signature on chain.

The wallet must support the selected Arc network, MPPI/registry calls and USDC authorization signing. Obtain credentials through your wallet service or secret store. Preserve pending and unknown results until the original operation is resolved.

2. Register the wallet with MPPI. Fund it with testnet USDC using your wallet provider. Download the official Arc testnet profile below as arc-profile.json and verify its SHA-256 using the linked instructions. Your trusted, importable module my_wallet must expose wallet(profile), returning your adapter.

Run these commands from your application's activated environment. Exclude .mppi-custom/ from version control before starting and retain it across restarts. Configure RPC credentials through your secret environment if needed.

Shell · after installing your wallet adapter
export ARC_RPC_URL_TESTNET=https://rpc.blockdaemon.testnet.arc.io
mppi-agent onboard --testnet --profile arc-profile.json \
  --config .mppi-custom/agent.json --wallet-factory my_wallet:wallet \
  --rpc-env ARC_RPC_URL_TESTNET

Continue only after complete: true; keep its agent_id. For exit code 2, rerun the same command and configuration to reconcile the original registration. For exit code 1, resolve the error without discarding records. This path registers the identity; it does not create the built-in Circle configuration or session signer.

3. Connect the client. Create and retain a separate fixed SessionSigner, then build the chain follower and contract calls for the same verified deployment. The composition guide below shows those bindings, including validation of the USDC signing domain. Pass your adapter directly to Client:

Python · inside your application, with prepared capabilities
from pathlib import Path
from mppi_agent import Client

client = Client(
    provider_origin,
    wallet=funding_wallet,
    signer=session_signer,
    chain=chain_follower,
    contract=contract_calls,
    checkpoint_path=Path(".mppi-custom/payments.json"),
    signer_reference=retained_signer_reference,
    agent_id=confirmed_agent_id,
    initial_session_tokens=chosen_token_budget,
)

Use the confirmed identity from step 2 and a deliberate positive funding budget. Keep the signer, its reference, the wallet journal and the separate payment checkpoint stable. This composition fragment requires your real capabilities; the linked example continues through request, close and client shutdown.

Who authorizes what

Opens and funds escrow

Funding wallet

Authorizes the fixed signer. Receives unused USDC on an eligible confirmed exit.

Signs off-chain proofs

Session signer

Signs runs, vouchers, attachment and cooperative close. Cannot move wallet funds itself.

Operates payment collection

Provider operator

Uses the session's frozen authority to submit eligible capture and close transactions.

Receives captured USDC

Payout recipient

Also has contract authority for eligible capture and close. Keep its signing custody outside serving.

Funding wallet → MPPI escrowCapture → recipientRefund → funding wallet

The funding wallet authorizes a fixed session signer when it opens escrow. That signer signs run, voucher, attachment and cooperative-close proofs. It cannot independently execute wallet-only funding or exit transactions.

The contract permits the session's frozen operator or recipient to perform eligible capture and close operations. Refunds always return to the funding wallet. A recipient update affects new sessions; it does not redirect an existing session.

The session signer is immutable for that session. Circle logout, login renewal or wallet policy changes do not revoke signatures it already issued. Ordinary amount, status and collection-deadline checks still apply.

Identity and discovery

ERC-8004 supplies a public identity and the provider's published service location and catalogue. Identity registration does not prove availability, execution quality or token counts. The SDK verifies the identity, origin, catalogue and trusted deployment before admitting paid work.

Retain the right state

Exclude the whole .mppi/ directory from version control and retain it across restarts. agent.json is configuration; the separate mode-0600 .signer file holds a plaintext local signing credential protected by OS permissions. Retain payment checkpoints and operation records too.

Renew Circle login for the same wallet when it expires. If execution loses its result before the Circle transaction ID is retained, the original operation remains unknown. Do not infer its identity from a similar history entry, delete the journal or submit a replacement to clear the uncertainty.

Wallets and accounts | Agents | MPPI Docs