Mercatura

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), outbox-delete (with item, the envelope's name), activity (read its activity), alerts (subscribe: with destination, the webhook URL; rules; and nonce, new random hex), alerts-list (its subscriptions) or alerts-revoke (with id, a subscription's or "all", and nonce).

Newest first: a Vlad account's claim, money added, gains out, withdrawals, moves, standing-order runs and its fund's trades (Lapo's), and its wallet's pay accounts' payments (with the key that signed), USDG in, withdrawals and key or owner changes. Each row has its time, transaction and one plain sentence. ref: an agentId, a wallet or a pay account. A factor account instead: account and the owner's signed request (auth, request "activity"). Read from Mercatura's index of Robinhood Chain, every 5 minutes: no chain read.

Subscribes an https webhook to a subject's events: ref, an agentId (a claimed Vlad account), a pay account, or a wallet that holds one. Mercatura POSTs { "type": "mercatura.webhook.verify", "nonce" } and the endpoint must answer 2xx with JSON { "verify": <hex HMAC-SHA256 of the nonce, keyed with the secret> }. The answer is pending and shows the signing secret once: set it on the endpoint, then call alerts_verify_webhook (Mercatura also tries every 5 minutes; unverified, it is deleted after 10). Each alert is a JSON POST with X-Mercatura-Timestamp and X-Mercatura-Signature: sha256=<hex HMAC-SHA256 of the timestamp, a dot, and the raw body, keyed with the secret>; 3 tries with backoff; turned off after 20 straight failures; at most one alert per rule per 10 minutes (more go together). The answer's unsubscribe.token stops it (alerts_unsubscribe). URL: https, standard port, a host name (no IP address). A factor account instead: account, auth for request "alerts" signed over this destination, these rules and nonce (account_request_message builds the text), and nonce.

Stops a push or webhook subscription with the unsubscribe token it was given (every alert body carries it too). The subscription and its URL or push keys are deleted.

For a webhook subscription that is still pending: Mercatura POSTs its check now ({ "type": "mercatura.webhook.verify", "nonce" }) and the subscription is active once the endpoint answers { "verify": <hex HMAC-SHA256 of the nonce, keyed with the secret> }. token: the unsubscribe token the subscription was given.

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.

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".

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

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.

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".

For a factor account's owner: every alert subscription on the account (id, channel, the host it goes to, rules, created, active, pending or off). Needs the owner's signed request for request "alerts-list".

For a factor account's owner: stops one alert subscription (id) or every one ("all"); each is deleted with its URL or push keys. Needs the owner's signed request for request "alerts-revoke", signed over this id and nonce (account_request_message builds the text); the nonce works once.

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".

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.

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. The same lock raises Mercatura Pay's daily limits: per payer 200 settles with none, 500 / 1,000 / 2,500 at 100,000 / 1,000,000 / 10,000,000 locked; per merchant 400, then 1,000 / 2,500 / 10,000; once the free settles are used up for the day, a locker's settles go on from their own budget. A pay account counts its current owner's lock. Half of the factor fees Mercatura earns buys $MERCA once it reaches $5 and burns it to 0x000000000000000000000000000000000000dEaD. Listing a factor needs no $MERCA.

The $MERCA a wallet has locked in the factor registry, how much counts for its tier (locked, no unlock requested), when a requested unlock is ready, and its Mercatura Pay tier (pay: its daily caps as a payer and a merchant). 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. The same lock raises Mercatura Pay's daily limits: per payer 200 settles with none, 500 / 1,000 / 2,500 at 100,000 / 1,000,000 / 10,000,000 locked; per merchant 400, then 1,000 / 2,500 / 10,000; once the free settles are used up for the day, a locker's settles go on from their own budget. A pay account counts its current owner's lock. Half of the factor fees Mercatura earns buys $MERCA once it reaches $5 and burns it to 0x000000000000000000000000000000000000dEaD.

The unsigned requestUnlock() transaction for `wallet`: all its locked $MERCA stops counting at once, for factor fees and Mercatura Pay's limits alike, and can be taken back with merca_unlock 7 days later.

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

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.

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".

One pay account: whether the address is one, its USDG, its owner, its top-up target and, with spender, that key's limits (per payment, per UTC day, expiry), what it spent today, what it has left and whether it is retired for good. Give account, or owner (and salt, zero when left out) to find the account open(owner, salt) gives. One read, kept 120 seconds.

The unsigned PayAccountFactory.fundWithETH(account, minUsdg) transaction with the ETH as value: swapped to USDG on the way in and sent to the account, at least minUsdg or it reverts (default: Chainlink's ETH price less 1%; the factory itself refuses below Chainlink less 2%, and while that price is older than 48 hours). Any wallet can fund any pay account. Sending USDG straight to the account works too.

The account's address and the unsigned PayAccountFactory.open(owner, salt) transaction, or with eth, openWithETH: the ETH is swapped to USDG on the way in (WETH/USDG pool), at least minUsdg or it reverts (minUsdg defaults to Chainlink's ETH price less 1%; the factory itself refuses below Chainlink less 2%, and while that price is older than 48 hours). Anyone can send it; the account is the owner's. salt is zero when left out: one account per owner.

For the account's owner: the unsigned setSpender(key, perPayment, perDay, expiry) transaction, so a separate key on the agent's machine can pay x402 APIs from the account within those limits (setting a key again replaces its limits), or with remove: true, removeSpender(key). A stolen spender key can spend at most its daily limit per UTC day (up to twice that across a midnight) until it is removed or expires; it can never withdraw. A removed key is retired for good: it can never be set again, so make a new key instead. Make the key on your own machine and send only its address.

For the account's owner: the unsigned withdraw(amount, to) transaction. Any amount, or "all", at any time; no one else can withdraw.

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).

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).

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.

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".

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.

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.

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.

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).

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.

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.

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.

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).

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.

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.

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.

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.

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.

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".

From an x402 402 response (its PAYMENT-REQUIRED header, base64, or the decoded JSON; a v1 body works too) and the payer: the EIP-712 TransferWithAuthorization to sign and the payment to send back (PAYMENT-SIGNATURE for v2, X-PAYMENT for v1), for USDG on Robinhood Chain. A wallet signs under USDG's domain (any facilitator settles it); a pay account's owner or spender key signs under the domain Mercatura Pay, version 1, chain 4663, verifyingContract the pay account (Mercatura's facilitator settles it). kind says which; left out, the factory is asked. Sign on your own machine: this tool never sees a key.