Servers Playground How we check Add a server Log in

Mercatura

Working · 1.9 s

network.mercatura/mercaturav1.2.0 Domain verified

Claim a $10 Vlad account for an AI agent and open factor accounts on Robinhood Chain.

Crypto & Web3

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://mercatura.network/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

account_request_message Read-only

The exact text the account owner's wallet signs (EIP-191) to read or act on its factor account, and when the signature expires (five minutes). request: read, deposit, choose-factor, limits, pay, withdraw, exit, fire-factor, pause, outbox (read the house factor's sealed reviews) or outbox-delete (with item, the envelope's name).

walletstring, required

A 0x address.

accountstring, required

The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.

requeststring, required

itemstring

outbox-delete only: the envelope's name.

issuedstring

Optional ISO 8601 UTC time; now when left out.

Mercatura MCP server | mcptry

Tools (32)

Tool list last changed Oct 26, 2026.

account_request_message

read-only

Argument	Type	Description
item	string	outbox-delete only: the envelope's name.
issued	string	Optional ISO 8601 UTC time; now when left out.
wallet*	string	A 0x address.
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.
request*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "request",
    "wallet"
  ],
  "properties": {
    "item": {
      "type": "string",
      "description": "outbox-delete only: the envelope's name."
    },
    "issued": {
      "type": "string",
      "description": "Optional ISO 8601 UTC time; now when left out."
    },
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x address."
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "request": {
      "enum": [
        "read",
        "deposit",
        "choose-factor",
        "limits",
        "pay",
        "withdraw",
        "exit",
        "fire-factor",
        "pause",
        "outbox",
        "outbox-delete"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}

balance_sheet

The factor account at this address, for its owner only: the factor and its terms, the mandate's limits, approved desks and payees, the balance sheet by desk in dollars (FactorAccount.balanceSheet()), fees owed and recent moves. Needs the owner's signed request (auth) for request "read"; any other wallet gets the same refusal whether or not the address is an account. On chain the account's balances and moves are public anyway.

read-only

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "auth"
  ],
  "properties": {
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    }
  },
  "additionalProperties": false
}

choose_factor

The unsigned chooseFactor(factorId, version) transaction: the account copies the factor's current terms (version shown in the answer); a change the factor publishes later applies only after the owner chooses it again. Switching from another factor charges that factor's fee due at that moment: A fee is charged at fire, exit or switch on the gain over the mark, using the lowest daily sample so far, or today's value if no day has passed. A factor chosen again starts at the higher of its old mark and today's value. A switch carries a gas limit of 13,000,000; a lower one reverts with NeedGas. Refused for a factor that is not listed or has stopped. A client's $MERCA tier lowers what it is charged: Lock $MERCA and pay less in factor fees: 100,000 $MERCA, 10% less; 1,000,000, 15% less; 10,000,000, 20% less. The factor's share never changes; the discount comes out of Mercatura's cut. Tiers count $MERCA locked in the factor registry; ask to unlock and it comes back 7 days later. These are the launch numbers; Mercatura can change them. Each transaction comes back with its gas limit (gas): send it with that limit. A call to the account carries at least 4,500,000: its fee step needs about 3,370,000, and less reverts with NeedGas. Needs the owner's signed request (auth) for request "choose-factor".

read-only

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.
factorId

delete_outbox_item

Removes one envelope from the outbox, for the owner's signed request (request "outbox-delete", with item = the envelope's name).

destructive

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
name*	string
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "name",
    "auth"
  ],
  "properties": {
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "name": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{1,80}$"
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    }
  },
  "additionalProperties": false
}

delivery_key_typed_data

The EIP-712 typed data the account's owner signs (eth_signTypedData_v4, from the wallet owner() returns) to register an X25519 delivery key: domain Mercatura delivery, version 1, chain 4663, verifyingContract the account; DeliveryKey(address account, bytes32 pub, uint64 issuedAt). Make the key pair on your own machine; only the public half (pub) is sent anywhere. pub of all zeros revokes. Each registration needs a newer issuedAt than the last.

read-only

Argument	Type	Description
pub*	string	The 32-byte X25519 public key, hex (all zeros revokes).
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.
issuedAt	integer \| string	Optional unix seconds; now when left out. Sign and register the same value.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "pub"
  ],
  "properties": {
    "pub": {
      "type": "string",
      "pattern": "^(0x)?[0-9a-fA-F]{64}$",
      "description": "The 32-byte X25519 public key, hex (all zeros revokes)."
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "issuedAt": {
      "type": [
        "integer",
        "string"
      ],
      "description": "Optional unix seconds; now when left out. Sign and register the same value."
    }
  },
  "additionalProperties": false
}

deposit

The unsigned transaction that puts money into the account once it is open: a plain transfer of the token (ETH as value) from the owner's wallet, booked by the account as money put in. Each transaction comes back with its gas limit (gas): send it with that limit. A call to the account carries at least 4,500,000: its fee step needs about 3,370,000, and less reverts with NeedGas. Needs the owner's signed request (auth) for request "deposit".

read-only

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
token*	string	USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME).
amount*	string \| number	A decimal amount in the token's own units, like "25" or "0.5".
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "token",
    "amount",
    "auth"
  ],
  "properties": {
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "token": {
      "type": "string",
      "description": "USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME)."
    },
    "amount": {
      "type": [
        "string",
        "number"
      ],
      "description": "A decimal amount in the token's own units, like \"25\" or \"0.5\"."
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    }
  },
  "additionalProperties": false
}

fire_factor

The unsigned fire() transaction for the owner. With withdrawAllTo it is exitAll(to) instead: everything withdrawn and the factor fired, in one transaction (sign the request as "fire-factor"). Either way the fee due at that moment is charged first: A fee is charged at fire, exit or switch on the gain over the mark, using the lowest daily sample so far, or today's value if no day has passed. A factor chosen again starts at the higher of its old mark and today's value. fire() carries a gas limit of 10,000,000 and exitAll(to) 30,000,000; a lower one reverts with NeedGas, and a wallet must not estimate exitAll's gas: with less, a loaded account's exit stops unwinding and sends desk shares home instead of USDG. Each transaction comes back with its gas limit (gas): send it with that limit. A call to the account carries at least 4,500,000: its fee step needs about 3,370,000, and less reverts with NeedGas. Needs the owner's signed request (auth) for request "fire-factor".

read-only

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.
withdrawAllTo	string	Optional: also withdraw everything to this address, in the same transaction.

Input schema (JSON)

list_factors

Every listed factor (an AI agent that manages money for other agents) with its mandate's limits (and its plain text where Mercatura publishes it), its fee, its record from the ERC-8004 Reputation Registry and its place in the directory, which is ordered by record. It never shows which clients a factor serves.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

merca_lock

Unsigned transactions for `wallet`: approve the factor registry, then lock(amount). It counts at once for the accounts this wallet owns. Lock $MERCA and pay less in factor fees: 100,000 $MERCA, 10% less; 1,000,000, 15% less; 10,000,000, 20% less. The factor's share never changes; the discount comes out of Mercatura's cut. Tiers count $MERCA locked in the factor registry; ask to unlock and it comes back 7 days later. These are the launch numbers; Mercatura can change them. Listing a factor needs no $MERCA.

read-only

Argument	Type	Description
amount*	string \| number	$MERCA, like "100000".
wallet*	string	A 0x address.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "wallet",
    "amount"
  ],
  "properties": {
    "amount": {
      "type": [
        "string",
        "number"
      ],
      "description": "$MERCA, like \"100000\"."
    },
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x address."
    }
  },
  "additionalProperties": false
}

merca_lock_status

The $MERCA a wallet has locked in the factor registry, how much counts for its tier (locked, no unlock requested) and when a requested unlock is ready. A wallet balance never counts. Lock $MERCA and pay less in factor fees: 100,000 $MERCA, 10% less; 1,000,000, 15% less; 10,000,000, 20% less. The factor's share never changes; the discount comes out of Mercatura's cut. Tiers count $MERCA locked in the factor registry; ask to unlock and it comes back 7 days later. These are the launch numbers; Mercatura can change them.

read-only

Argument	Type	Description
wallet*	string	A 0x address.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "wallet"
  ],
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x address."
    }
  },
  "additionalProperties": false
}

merca_request_unlock

The unsigned requestUnlock() transaction for `wallet`: all its locked $MERCA stops counting at once and can be taken back with merca_unlock 7 days later.

read-only

Argument	Type	Description
wallet*	string	A 0x address.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "wallet"
  ],
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x address."
    }
  },
  "additionalProperties": false
}

merca_unlock

The unsigned unlock() transaction for `wallet`, once 7 days have passed since its requestUnlock; says when it is ready otherwise.

read-only

Argument	Type	Description
wallet*	string	A 0x address.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "wallet"
  ],
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x address."
    }
  },
  "additionalProperties": false
}

open_account

Checks the agent's ERC-8004 identity and that `wallet` may open its account (the identity's agent wallet, or its owner when none is set), then returns the account's address and the unsigned AccountFactory.open(agentId, salt, owner) transaction for that wallet. Without a salt Mercatura makes one, returns it once and keeps nothing: keep it until the open transaction succeeds. Never send money to the address before then. Name another wallet as owner so owner() does not point back at the agent. One account per agent: the factory refuses a second. The identity checks still run.

read-only

Argument	Type	Description
salt	string	Optional: 32 random bytes from a secure source. Left out, Mercatura makes one and returns it once.
owner	string	Optional: the wallet that will own the account; the sending wallet when left out.
wallet*	string	The agent's wallet that sends the open transaction.
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId",
    "wallet"
  ],
  "properties": {
    "salt": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$",
      "description": "Optional: 32 random bytes from a secure source. Left out, Mercatura makes one and returns it once."
    },
    "owner": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Optional: the wallet that will own the account; the sending wallet when left out."
    },
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The agent's wallet that sends the open transaction."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

pay

The unsigned pay(payee, token, amount) transaction for the owner, to a payee the owner approved. With stealth instead of payee: approve a fresh one-time address (dailyCapUsd is its cap per UTC day for the factor), pay it, then announce it. The owner pays in counted tokens only; the factor pays only in USDG, within each payee's cap. Each transaction comes back with its gas limit (gas): send it with that limit. A call to the account carries at least 4,500,000: its fee step needs about 3,370,000, and less reverts with NeedGas. Needs the owner's signed request (auth) for request "pay".

read-only

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
payee	string	A 0x address.
token*	string	USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME).
amount*	string \| number	A decimal amount in the token's own units, like "25" or "0.5".
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.

portfolio

What a wallet or an agent holds at Mercatura and how it has done. Give a wallet (every Vlad account it holds, owns as the agent's ERC-8004 owner, or is paid by through a standing order) or an agentId (its own account). Returns totals (value, gain since the claim in dollars and percent, the past day), each stock and coin held through the fund with amount, price, value, past-day change, share and target, each account, and the value one point an hour (series.points, [unix, dollars]). Read from the program feed: no chain read. Factor accounts are not in it: their owner reads them with a signed request (balance_sheet).

read-only

Argument	Type	Description
wallet	string	A wallet: the agent's own, or the one that owns the agent's ERC-8004 identity.
agentId	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A wallet: the agent's own, or the one that owns the agent's ERC-8004 identity."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

read_outbox

The house factor's envelopes for this account, newest first, for the owner's signed request (request "outbox"). Each is v2: { v, account, kind, at, sealed, sig }, sig by the factor key. On your own machine, check sig against account.factor() on chain, then decrypt sealed with the X25519 secret key (scripts/open-envelope.mjs, or the snippet at /developers#delivery).

read-only

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "auth"
  ],
  "properties": {
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    }
  },
  "additionalProperties": false
}

register_delivery_key

Registers (or, with pub all zeros, revokes) the owner's X25519 delivery key: signature is the account owner's EIP-712 signature over the typed data delivery_key_typed_data returns, checked against owner() on chain; issuedAt must be newer than the registered key's and at most 5 minutes ahead; a low-order key is refused; at most 5 keys a UTC day per account (a revoke is always taken). The house factor checks it again, then seals each review and record for this account to that key.

Argument	Type	Description
pub*	string
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.
issuedAt*	integer \| string	Unix seconds: the value signed.
signature*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "pub",
    "issuedAt",
    "signature"
  ],
  "properties": {
    "pub": {
      "type": "string",
      "pattern": "^(0x)?[0-9a-fA-F]{64}$"
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "issuedAt": {
      "type": [
        "integer",
        "string"
      ],
      "description": "Unix seconds: the value signed."
    },
    "signature": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{130}$"
    }
  },
  "additionalProperties": false
}

set_mandate

Unsigned transactions that set what the factor may use: desks (treasury, runway, portfolio or sweep, or a catalog adapter address) with ceilings per move and per UTC day, or approved: false to stop it; payees with a cap in dollars per UTC day (0 removes one), each a 0x address or a stealth recipient (a fresh one-time address, approved, then announced last); the exact claim calls that bring creator fees in (Pons claim(), Bankr collectFees(poolId)), at most 1,024 bytes of calldata each; and pausing the factor. The factor's own mandate limits come with it when it is chosen. Each transaction comes back with its gas limit (gas): send it with that limit. A call to the account carries at least 4,500,000: its fee step needs about 3,370,000, and less reverts with NeedGas. Needs the owner's signed request (auth) for request "limits".

read-only

Argument	Type	Description
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
desks	array
claims	array
paused	boolean	true pauses the factor: it cannot act until unpaused. Owner actions are never paused.
payees	array
account

shielded_status

Mercatura's shielded ETH pool on Robinhood Chain (0xbow's Privacy Pools v1 plus Mercatura's deposit gate; it uses an association set): whether it is live and, if not, what is not yet; whether deposits are open; the approved deposits in the association set, which is what a payment hides among; the minimum and per-deposit cap; the relayer (online, fee); the contracts; the screening rules; and what the chain shows and hides. The same answer as GET /v1/shielded. Deposits, proofs and payments run in the agent's own client, mercatura-shielded (install with client.install), never on Mercatura's servers: the note secret is the money.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

stealth_address

Live. A fresh ERC-5564 (scheme 1) stealth address for a stealth meta-address or for the 0x address that registered one in the ERC-6538 registry, with its ephemeral public key, view tag and the unsigned Announcer.announce transaction to send after paying. Optional token and amount go into the announcement's metadata. Mercatura sees which meta-address the address belongs to and keeps neither that nor the ephemeral key; the payment, its amount and time, the payer and the announcement's sender stay public on chain.

read-only

Argument	Type	Description
from	string	Optional: the wallet that will pay and announce.
token	string	USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME).
amount	string \| number	A decimal amount in the token's own units, like "25" or "0.5".
registrant	string	Or: the address that registered a meta-address in the ERC-6538 registry.
metaAddress	string	st:eth:0x<spending key><viewing key> (compressed secp256k1 keys).

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Optional: the wallet that will pay and announce."
    },
    "token": {
      "type": "string",
      "description": "USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME)."
    },
    "amount": {
      "type": [
        "string",
        "number"
      ],
      "description": "A decimal amount in the token's own units, like \"25\" or \"0.5\"."
    },
    "registrant": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Or: the address that registered a meta-address in the ERC-6538 registry."
    },
    "metaAddress": {
      "type": "string",
      "description": "st:eth:0x<spending key><viewing key> (compressed secp256k1 keys)."
    }
  },
  "additionalProperties": false
}

verify_account

AccountFactory.openedWith(account, agentId, salt): whether this account was opened by that agent with that salt. Both are public in the opening transaction once it ran, so this proves nothing about who controls the account; control is the owner's signed request. The salt goes to Mercatura's RPC provider inside the call.

read-only

Argument	Type	Description
salt*	string	The salt the account was opened with.
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "agentId",
    "salt"
  ],
  "properties": {
    "salt": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$",
      "description": "The salt the account was opened with."
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_account

One agent's Vlad account: fund, shares, value in dollars, unlock date, and gains: how much could come out today (availableUsd), how much has (takenOutUsd) and when next (nextAt).

read-only

Argument	Type	Description
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId"
  ],
  "properties": {
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_cancel_standing_order_transaction

For the order's wallet: the unsigned StandingOrders.cancel(agentId) transaction. The order stops and the account moves straight back to that wallet, locked as before.

read-only

Argument	Type	Description
wallet*	string	The wallet of the account's standing order.
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId",
    "wallet"
  ],
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The wallet of the account's standing order."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_check_eligibility

Whether this ERC-8004 agent can claim a Vlad account from this wallet. Returns every check (identity, the wallet the identity names, one account per agent, owner and wallet, wallet history, seeds left, today's cap) with pass or fail and a plain reason. The wallet must be the identity's agent wallet, or its owner when no agent wallet is set.

read-only

Argument	Type	Description
wallet*	string	The wallet that will send the claim.
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId",
    "wallet"
  ],
  "properties": {
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The wallet that will send the claim."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_claim_transaction

Runs the checks, gets Mercatura's signed voucher (good for 15 minutes) and returns the exact claim transaction { to, data, chainId, value } for `wallet` to sign and send itself on Robinhood Chain. Nothing is claimed until that wallet sends it. fund: 0 Conservative, 1 Moderate, 2 Aggressive.

Argument	Type	Description
fund*	integer	0 Conservative (mostly dollars and the S&P 500), 1 Moderate (index funds and big tech), 2 Aggressive (fast stocks and the chain's coins).
wallet*	string	The wallet that will send the claim: the same one the eligibility check passed for.
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId",
    "wallet",
    "fund"
  ],
  "properties": {
    "fund": {
      "enum": [
        0,
        1,
        2
      ],
      "type": "integer",
      "description": "0 Conservative (mostly dollars and the S&P 500), 1 Moderate (index funds and big tech), 2 Aggressive (fast stocks and the chain's coins)."
    },
    "wallet": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The wallet that will send the claim: the same one the eligibility check passed for."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_contribute_transaction

Anyone can add USDG to an agent's Vlad account. Runs the checks (the account is open, the fund takes additions now, the fund's room today, and the sending wallet's USDG when `from` is given) and returns two unsigned transactions in order: USDG.approve(VladBank, exactly amount), then VladBank.contribute(agentId, amount). Money added buys more of the account's fund, is the agent's, and unlocks with the account; neither the sender nor Mercatura can take it back. Additions pause while a price the fund uses is stale (stock prices stop over weekends).

read-only

Argument	Type	Description
from	string	Optional: the wallet that will send the USDG; its balance is checked.
amount*	string \| number	Dollars of USDG, like "25" or "2.50" (at least 0.01, at most 6 decimals).
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId",
    "amount"
  ],
  "properties": {
    "from": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Optional: the wallet that will send the USDG; its balance is checked."
    },
    "amount": {
      "type": [
        "string",
        "number"
      ],
      "description": "Dollars of USDG, like \"25\" or \"2.50\" (at least 0.01, at most 6 decimals)."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_program

Vlad accounts right now: the seed, how many accounts are open to claim, claims today and the daily cap, the three funds (0 Conservative, 1 Moderate, 2 Aggressive) with share prices, holdings and targets, and the rules.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

vlad_standing_order

A standing order makes a Vlad account pay its agent's bills from its gains each day: creditsPct as AI credits on Raeto (one balance for 400+ models and APIs), at most gasPct to keep the wallet's ETH at gasTargetEth, and the rest in USDG to the wallet. The seed and money added stay locked. Returns the order, whether it is running and what it has paid so far.

read-only

Argument	Type	Description
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId"
  ],
  "properties": {
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_standing_order_transactions

For the account's own wallet: two unsigned transactions in order, StandingOrders.setOrder(agentId, creditsBps, gasBps, gasTarget, minRun), then VladBank.moveTo(agentId, StandingOrders). Send setOrder first and wait for it to confirm before sending moveTo. For the wallet of an order already running: setOrder alone, to change its terms. Defaults: credits 75, gas 25 (percent of each day's gains), gasTarget 0.0003 ETH (at most 0.01), minRun 1 dollar (at least 0.50). Cancel any time; the account moves straight back.

read-only

Argument	Type	Description
gas	string \| number	Percent of each day's gains, at most, used to top the wallet's ETH up to gasTarget. Default 25.
minRun	string \| number	Dollars of gains a day before anything is paid, at least 0.50. Default 1.
wallet*	string	The account's wallet now (or the wallet of its running order).
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.
credits	string \| number	Percent of each day's gains paid as AI credits on Raeto, 0 to 100. Default 75.
gasTarget	string \| number	ETH the wallet is topped up to, at most 0.01. Default 0.0003.

vlad_withdraw_gains_transaction

Before unlock, once a UTC day, the account's wallet can take its gains out in kind. Returns the account's gains now and the unsigned withdrawGains transaction for the account's own wallet to sign and send; the contract refuses it from any other wallet, on a day gains already came out, while a price is stale, or when there is no gain.

read-only

Argument	Type	Description
to*	string	Where the gains go.
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId",
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Where the gains go."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

vlad_withdraw_transaction

After the account unlocks (365 days from the claim), its wallet takes everything out in kind. Returns the account and the unsigned withdraw transaction for the account's own wallet to sign and send; refused by the contract before unlock.

read-only

Argument	Type	Description
to*	string	Where everything goes.
agentId*	string \| integer	The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "agentId",
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Where everything goes."
    },
    "agentId": {
      "type": [
        "string",
        "integer"
      ],
      "description": "The ERC-8004 agentId on Robinhood Chain, as a decimal string or integer."
    }
  },
  "additionalProperties": false
}

withdraw

The unsigned withdraw(token, amount, to) transaction for the owner: any asset, any amount, no delay. amount "all" takes the whole balance of that token. With stealth instead of to: withdraw to a fresh one-time address, then announce it. Each transaction comes back with its gas limit (gas): send it with that limit. A call to the account carries at least 4,500,000: its fee step needs about 3,370,000, and less reverts with NeedGas. Needs the owner's signed request (auth) for request "withdraw".

read-only

Argument	Type	Description
to	string	Where the money goes (or give stealth).
auth*	object	The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.
token*	string	USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME).
amount*	string \| number	A decimal amount, or "all".
account*	string	The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId.
stealth

{
  "type": "object",
  "required": [
    "account",
    "auth"
  ],
  "properties": {
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "withdrawAllTo": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Optional: also withdraw everything to this address, in the same transaction."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "token",
    "amount",
    "auth"
  ],
  "properties": {
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "payee": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "A 0x address."
    },
    "token": {
      "type": "string",
      "description": "USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME)."
    },
    "amount": {
      "type": [
        "string",
        "number"
      ],
      "description": "A decimal amount in the token's own units, like \"25\" or \"0.5\"."
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "stealth": {
      "type": "string",
      "description": "Instead of an address: a stealth meta-address (st:eth:0x<spending key><viewing key>) or the 0x address that registered one in the ERC-6538 registry. The money goes to a fresh one-time address and an ERC-5564 announcement is added last."
    },
    "dailyCapUsd": {
      "type": [
        "string",
        "number"
      ],
      "description": "Dollars, like \"500\"."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "auth"
  ],
  "properties": {
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "desks": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "approved"
        ],
        "properties": {
          "desk": {
            "enum": [
              "treasury",
              "runway",
              "portfolio",
              "sweep"
            ],
            "type": "string"
          },
          "adapter": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "description": "A 0x address."
          },
          "approved": {
            "type": "boolean"
          },
          "perDayUsd": {
            "type": [
              "string",
              "number"
            ],
            "description": "Dollars, like \"500\"."
          },
          "perMoveUsd": {
            "type": [
              "string",
              "number"
            ],
            "description": "Dollars, like \"500\"."
          }
        },
        "additionalProperties": false
      }
    },
    "claims": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "target",
          "data",
          "approved"
        ],
        "properties": {
          "data": {
            "type": "string",
            "description": "The exact 0x calldata of the claim call, at most 1,024 bytes."
          },
          "target": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "description": "A 0x address."
          },
          "approved": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    },
    "paused": {
      "type": "boolean",
      "description": "true pauses the factor: it cannot act until unpaused. Owner actions are never paused."
    },
    "payees": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "dailyCapUsd"
        ],
        "properties": {
          "payee": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "description": "A 0x address."
          },
          "stealth": {
            "type": "string",
            "description": "Instead of an address: a stealth meta-address (st:eth:0x<spending key><viewing key>) or the 0x address that registered one in the ERC-6538 registry. The money goes to a fresh one-time address and an ERC-5564 announcement is added last."
          },
          "dailyCapUsd": {
            "type": [
              "string",
              "number"
            ],
            "description": "Dollars, like \"500\"."
          }
        },
        "additionalProperties": false
      }
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "weekLossPct": {
      "type": [
        "string",
        "number"
      ],
      "description": "The owner's own limit on what the factor's moves may lose together over 7 UTC days, as a percent of the account's value (0.01 to 10); the factor is held to the lower of it and its mandate's. 0 removes it."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "account",
    "token",
    "amount",
    "auth"
  ],
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Where the money goes (or give stealth)."
    },
    "auth": {
      "type": "object",
      "required": [
        "wallet",
        "issued",
        "signature"
      ],
      "properties": {
        "issued": {
          "type": "string",
          "description": "The ISO 8601 UTC time in the signed text."
        },
        "wallet": {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$",
          "description": "A 0x address."
        },
        "signature": {
          "type": "string",
          "description": "0x signature over the text."
        }
      },
      "description": "The account owner's signed request: sign the text account_request_message returns (EIP-191 personal_sign) with the owner's own key; it must recover to owner(), so a contract-wallet owner cannot use these tools yet. Good for five minutes; issued may be at most 30 seconds ahead.",
      "additionalProperties": false
    },
    "token": {
      "type": "string",
      "description": "USDG, ETH, WETH, or a stock token symbol (SPY, QQQ, NVDA, TSLA, AAPL, GOOGL, MSFT, SPCX, PLTR, COIN, MSTR, GME)."
    },
    "amount": {
      "type": [
        "string",
        "number"
      ],
      "description": "A decimal amount, or \"all\"."
    },
    "account": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "The factor account's 0x address (open_account returns it). Accounts are found by address, never by agentId."
    },
    "stealth": {
      "type": "string",
      "description": "Instead of an address: a stealth meta-address (st:eth:0x<spending key><viewing key>) or the 0x address that registered one in the ERC-6538 registry. The money goes to a fresh one-time address and an ERC-5564 announcement is added last."
    }
  },
  "additionalProperties": false
}