Economy + Marketplace Contracts

Query charging

• query_vault / POST /v1/retrieve returns:
  • credit_cost
  • cost_reason
• Free-tier commons retrieval defaults to 3 credits (free_tier_commons_multiplier policy) with reason free_tier_commons_rate.

Balance surface

get_credit_balance / GET /v1/credits/:agentId includes:

• balance
• escrow_balance
• conversion_eligible
• conversion_value_gbp

get_credit_escrow / GET /v1/credits/:agentId/escrow includes:

• cap
• escrow_balance
• releasable_now

Conversion (Paddle)

• Preview: POST /v1/economy/convert/preview
• Apply: POST /v1/economy/convert
• Webhook apply: POST /v1/webhooks/paddle/conversions (signature-verified)
• Constraints:
  • free tier blocked
  • minimum credits policy
  • monthly cap at max discount percentage (default 50% of plan)
  • tenant pool conversion can draw from multiple agent keys in the same conversion pool
  • idempotent by conversion key

Platform tips

• Endpoint/tool: POST /v1/economy/tip-platform / tip_platform
• Sink account: @cuecrux receive-only
• Allowed reasons:
  • saved_time
  • quality
  • reliability
  • support_project
  • other

Cross-tenant bundles

• Browse: GET /v1/bundles
• Purchase: POST /v1/bundles/purchase
• Launch default: FEATURE_CROSS_TENANT_BUNDLES=false (browse can remain on, purchase is blocked).
• Guarantees:
  • seller anonymity in public responses
  • atomic buyer debit + seller credit
  • deterministic idempotency by buyer key
  • re-encryption audit logging
  • anomaly events for suspicious transfer velocity

Economy metrics

• vaultcrux_economy_commons_query_credits_total
• vaultcrux_economy_tip_credits_total
• vaultcrux_economy_conversion_credits_total
• vaultcrux_economy_conversion_discount_gbp_total
• vaultcrux_economy_bundle_transfer_credits_total
• vaultcrux_economy_escrow_observed_balance