mercuri-finance/mercurifi-sdk

launch.mercuri.finance ·
docs.mercuri.finance ·
contracts
TypeScript (npm @mercurifi/sdk) and Python (PyPI mercurifi) SDKs for Mercurifi Agent Accounts on Arc: an account
that holds USDC and Launch tokens, and agent keys that trade for it inside caps the owner sets. Your bot or AI agent
holds a key that can buy and sell on Mercurifi Launch bonding curves and graduated pools, launch tokens and claim
creator fees. It can never withdraw: only the owner can, and only to itself. Mercurifi never runs agents and never holds
an agent key.
**Contents** · Install · Deployment · Quickstart ·
Loss bound · Owner and agent · Examples · Units ·
Chain-only or with the API · Errors ·
ERC-8004 identity · Circle Wallets ·
Local development · Verify a release · Security ·
License
Install
Both are at 1.0.0 on npm and PyPI. Each package is
built and published by this repository's release workflows, with signed provenance; see
Verify a release. Install only these two names: anything else is not ours
(docs/reserved-names.md).
Deployment
Agent Accounts are deployed on Arc mainnet and testnet, version 1.0.0-beta.1.
**No third-party audit has been performed yet; start with small amounts.** A network or address book without a
recorded agent deployment throws NotDeployedError for agent operations. A local chain also works (chain 31337,
loopback RPC, a local address book).
| Contract | Address (mainnet, chain 5042) | Mutability |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
| AgentAccountFactory | 0x816C7269FDcf621b7d8cb99A5AfbE9daddBd3b58 | immutable |
| AgentPolicyRegistry | 0x318A0e1353E812A36FC7C52a88Af8D6A96909483 | immutable |
| AgentAccount (implementation) | 0x36acC3Eb67571E592A45c88656c4B3c4f7Fb7beE | immutable |
| Contract | Address (testnet, chain 5042002) | Mutability |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| AgentAccountFactory | 0x6D56A15c25782FF638943A4E81A1eD1ea862C9Bd | immutable |
| AgentPolicyRegistry | 0xcfCDA6a022314eA7Ae995cCf88e4eeB3A8802C69 | immutable |
| AgentAccount (implementation) | 0xD11567fDfc9833E39E7EEbB0964c7bB7f4FF40b5 | immutable |
The SDK checks each address's runtime code hash against its address book before the first call, so a wrong RPC or a
look-alike contract fails before anything is signed. The source, the deployment record and the bytecode verification
are in mercuri-agent-contracts. Testnet USDC
for gas and deposits: faucet.circle.com (Arc testnet).
Quickstart (Arc testnet)
The owner wallet creates an account with a fresh agent key, deposits USDC and gives the key a little gas; the agent key
then buys a Launch token.
The package READMEs go further: TypeScript and
Python (including the blocking Client for scripts and notebooks).
Loss bound
A stolen agent key can still lose money through bad trades: buying an attacker's token, or selling the account's holdings into a price the attacker pushed down. **That loss is bounded by the account's caps, not prevented.** Per period, the bound is the USDC spend cap plus the sell cap, which is measured at the account's own cost basis. It keeps accruing every period until the key is revoked or expires.
Read docs/security-model.md before you give a key to a program.
Owner and agent
The owner (main wallet) creates the account, deposits and sets policy; an agent key trades inside the policy. Owner
settings are on the policy registry and funds are on the account:
| | |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |