feat: `POST /api/agent-accounts` — backend-mediated aibtc-acct creation (mcp-server#553 Option 3)

[secret-mars]

Why

aibtc-mcp-server PR #553 adds 15 tools for operating an existing aibtc-acct (the cohort-0 two-role smart wallet). One of them, agent_account_deploy, tries to self-deploy a fresh account by cloning a reference contract's source. @biwasxyz's mainnet test on the PR thread confirmed this can't work — the aibtc-acct contract calls auto-register-agent-account at deploy time, and agent-account-registry asserts tx-sender = ATTESTOR_DEPLOYER (SP2Z94F6QX847PMXTPJJ2ZCCN79JZDW3PJ4E6ZABY), so any non-AIBTC deployer aborts:

mainnet deploy tx 9cb45a9a6073532e103f360f260bd09b5149123a63a61de92924a0ccd7a6b707 aborted; ~0.02 STX fee burned.

The current path forward on #553 is to strip the deploy tool from this PR (so the 14 operate tools land cleanly) and re-add it later as a thin wrapper around an AIBTC-backend creation endpoint. This issue tracks the backend side of that.

Proposed endpoint

POST /api/agent-accounts
  body: { ownerBtcAddress, agentBtcAddress, [referenceContract] }
  -> 200 { contractId, txid, status: "submitted" | "confirmed" }
  -> 400 { error: "invalid_address" | "invalid_reference" | ... }
  -> 401 { error: "unauthorized" }     # if request must be signed
  -> 409 { error: "account_exists", contractId, txid }
  -> 429 { error: "rate_limited" }

The backend (which holds the ATTESTOR_DEPLOYER key) signs and broadcasts the deploy + the registry's register-agent-account step on the requester's behalf, then returns the deployed contract id once it lands (or the in-flight txid + the lookup endpoint).

Auth / safety questions for maintainers

• Who can call this? Open to any verified BTC address (i.e. anyone with POST /api/register already done)? Genesis-level only? Signed-request only (BIP-322 over the body)?
• Idempotency — if the deterministic contract name (aibtc-acct-<ownerFirst5>-<ownerLast5>-<agentFirst5>-<agentLast5> per referenceAgentAccount in fix(inbox): clarify pending-payment success to reduce SENDER_NONCE_DUPLICATE resend loops #553) already exists on chain, return 409 with the existing contractId rather than aborting deploy fee a second time.
• Rate limit / sat cost — should creation be x402-paid (treat as a paid endpoint), since the backend is burning STX + competing for nonce slots? This also makes spam economically self-limiting.
• Reference contract whitelist — referenceContract defaults to mainnet cohort-0; if callers can override, that surface should be whitelisted (otherwise a malicious caller could deploy from an arbitrary source).

Caller

Once this lands, agent_account_deploy returns to the MCP tool surface as a ~30-LOC wrapper:

const res = await fetch(`${AIBTC_BASE}/api/agent-accounts`, {
  method: "POST",
  body: JSON.stringify({ ownerBtcAddress, agentBtcAddress }),
  headers: { "Content-Type": "application/json", ...(signed && { "X-BIP322-Signature": sig }) },
});

cleaner than the current 150 LOC of source-mutation + post-condition assembly + headless deploy signing.

Optional path B

If the platform decides the deploy path should remain bot-only (no self-service by agents), close this as wontfix and the MCP tool stays dropped permanently — the 14 operate tools cover the actual agent-side surface and the aibtc.com UI continues to be the one entry point for account creation.

cc @whoabuddy @biwasxyz — filing per the offer at aibtcdev/aibtc-mcp-server#553 (comment)

[biwasxyz]

Closing as not planned, taking the "optional path B" the issue itself offers.

No maintainer has picked this up in the two months since filing, and account creation via aibtc.com remains the single entry point, so the backend-mediated deploy endpoint has no committed consumer. The 14 operate tools in aibtc-mcp-server#553 cover the agent-side surface without it.

If self-service aibtc-acct creation becomes a product requirement, this should be re-filed with the auth model decided up front (who may call, signed vs x402-paid, reference-contract allowlist) rather than left open as an unanswered design question.