Payee developer documentation

CREATE TABLE IF NOT EXISTS agent_api_keys (
  id                UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  profile_id        UUID NOT NULL REFERENCES profiles(id) ON DELETE CASCADE,
  key_hash          TEXT UNIQUE NOT NULL,      -- SHA-256 of the raw key
  name              TEXT NOT NULL,             -- user-defined label
  key_prefix        TEXT NOT NULL,             -- first 12 chars for display
  daily_limit       NUMERIC(18, 6) NOT NULL DEFAULT 10.000000,
  single_tx_limit   NUMERIC(18, 6) NOT NULL DEFAULT 5.000000,
  spent_today       NUMERIC(18, 6) NOT NULL DEFAULT 0.000000,
  last_spent_reset  TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
  is_active         BOOLEAN        NOT NULL DEFAULT TRUE,
  created_at        TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
  last_used_at      TIMESTAMPTZ
);

ALTER TABLE agent_api_keys ENABLE ROW LEVEL SECURITY;
CREATE POLICY "own_agent_keys" ON agent_api_keys
  FOR ALL USING (auth.uid() = profile_id);

CREATE TABLE IF NOT EXISTS agent_wallets (
  id                  UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  profile_id          UUID NOT NULL REFERENCES profiles(id) ON DELETE CASCADE,

  -- Circle Agent Wallet (from: circle wallet list --output json)
  circle_wallet_id    TEXT NOT NULL,       -- Circle internal UUID
  circle_address      TEXT NOT NULL,       -- 0x... on-chain address
  chain               TEXT NOT NULL DEFAULT 'BASE',

  -- Identity (globally unique across profiles.username AND here)
  agent_paytag        TEXT UNIQUE NOT NULL, -- e.g. "my-claude-agent"
  display_name        TEXT,
  agent_type          TEXT DEFAULT 'coding', -- coding | trading | service | custom

  -- Budget policy (display + alerting; enforcement is CLI-side)
  daily_limit         NUMERIC(18, 6),
  per_tx_limit        NUMERIC(18, 6),

  -- State
  is_active           BOOLEAN NOT NULL DEFAULT TRUE,
  is_paused           BOOLEAN NOT NULL DEFAULT FALSE,
  last_synced_at      TIMESTAMPTZ,
  created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

ALTER TABLE agent_wallets ENABLE ROW LEVEL SECURITY;
CREATE POLICY "own_agent_wallets" ON agent_wallets
  FOR ALL USING (auth.uid() = profile_id);

CREATE TABLE IF NOT EXISTS agent_wallet_transactions (
  id                   UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  agent_wallet_id      UUID NOT NULL REFERENCES agent_wallets(id) ON DELETE CASCADE,
  profile_id           UUID NOT NULL REFERENCES profiles(id) ON DELETE CASCADE,

  -- Idempotency key: txHash-logIndex (onchain) or Circle tx UUID
  circle_tx_id         TEXT UNIQUE NOT NULL,
  source               TEXT NOT NULL DEFAULT 'circle', -- 'circle' | 'onchain'

  tx_direction         TEXT NOT NULL, -- 'INBOUND' | 'OUTBOUND'
  amount_usdc          NUMERIC(18, 6) NOT NULL,
  destination_address  TEXT,
  source_address       TEXT,
  state                TEXT NOT NULL DEFAULT 'COMPLETE',
  blockchain_tx_hash   TEXT,

  -- Enrichment (resolved after sync)
  destination_paytag   TEXT,    -- resolved @paytag if destination is a Payee user
  service_label        TEXT,    -- human-readable label from Circle metadata

  circle_created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  synced_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_awt_agent  ON agent_wallet_transactions(agent_wallet_id);
CREATE INDEX idx_awt_date   ON agent_wallet_transactions(circle_created_at DESC);

ALTER TABLE agent_wallet_transactions ENABLE ROW LEVEL SECURITY;
CREATE POLICY "own_agent_txs" ON agent_wallet_transactions
  FOR ALL USING (auth.uid() = profile_id);