Venue Binding

One authority binds to many venues — declaratively, so adding a venue is data + one adapter, not a rewrite.

The venue capability contract

Every venue is described once, as data, in a registry. The contract drives whether the pre-bind gate runs, whether the venue is ACP-native, what funding/readiness/approval gates apply, and its honest maturity.

interface VenueCapabilityContract {
  venueId: string;
  authModel: string;        // economyos_agent_wallet_plus_acp | agent_wallet_plus_deposit | …
  signingModel: string;     // provider_agent_wallet | eip1271 | api_wallet | route_proof | …
  perUserAuthorityRequired: boolean;   // gates the pre-bind check
  acpNative: boolean;       // virtuals / degenclaw
  nativeChain: string | null;
  bindingSupported: boolean;           // a promise the backend can service it
  maturity: "reference" | "production";
  integrationNotes: string;
}

Lesson burned in

A venue's bindingSupported flag is a promise the backend can actually service it. Keep it false until the adapter exists — flipping it early routes a "coming soon" venue into live paths and breaks. The contract is a contract.

The universal pre-bind gate

The keystone: no venue binding, signer, deposit wallet, or credential is created until parent authority is resolved.

ANY venue bind / setup / fund / execute
  → pre-bind gate: resolve_authority(user, venue, action, allowAutoCreate)
      ok  → proceed to venue setup
      blocked → exact status, NO venue artifacts created

Status taxonomy (never a generic "signer_required")

Status	Meaning	ok
authority_ready	Parent authority resolved	✅
agent_wallet_created	Mode A auto-created this call	✅
agent_wallet_required	No authority; read path or auto-create disabled	❌
virtuals_identity_required	ACP-native venue needs a linked Virtuals identity	❌
virtuals_signer_required	Identity present but signer not ready	❌
owner_handoff_required	Pending Virtuals link needs an owner action	❌
authority_reconciliation_required	virtuals provider but proof not verified	❌
unsupported_authority_source	Provider not in privy / virtuals	❌
venue_contract_missing	Venue not in the registry	❌

allowAutoCreate — the write/read distinction

• Write/setup intent ("bind X", a setup endpoint): allowAutoCreate=true → Mode A is minted if no authority exists.
• Read/status/passive (status checks, market search, polling, GETs): allowAutoCreate=false → returns agent_wallet_required, never silently creates a wallet.

The bind lifecycle

explicit bind intent → pre-bind gate (allowAutoCreate=true)
  → Mode A auto-created if needed | Mode B honored if proof verified
  → create/load VenueBinding (child of AgentAuthority)
  → venue-specific setup (deposit wallet / API wallet / CLOB / route-proof)
  → readiness (funding / approvals / signer)
  → ready  (or ready_but_live_locked if live flags off)

Many bindings live under one authority — that is what makes "bind three venues" and "show all positions across venues" possible. Next: Cross-chain funding.