GraphQL Mutations

Active mutations use snake_case names and mostly return a success / data / error envelope. The auth, organization, passkey, and onboarding mutations that powered the old web dashboards are still in the schema but are @deprecated (dashboard sunset) — see the bottom of this page.

The canonical way to authenticate a programmatic client is the CLI signed-request scheme or a REST API key — not the deprecated password login flow. See Authentication.

Exchange Accounts

mutation {
  create_exchange_account(exchange_account: {
    exchange_name: "binance"
    account_name: "My Binance"
    trading_type: "spot"
    api_key: "..."
    api_secret: "..."
  }) {
    success
    data { id exchange_name is_active }
  }
}

mutation { update_exchange_account(id: "exc_123", exchange_account: { account_name: "Renamed" }) { success data { id } } }
mutation { delete_exchange_account(id: "exc_123") { success } }
mutation { sync_exchange_account(id: "exc_123") { success data { id balance last_sync_at } } }
mutation { test_exchange_account(account: { exchange_name: "binance", api_key: "...", api_secret: "..." }) { success error } }

Strategies

mutation {
  create_strategy(strategy: {
    exchange_account_id: "exc_123"
    name: "BTC Momentum"
    risk_level: 3
  }) { success data { id name } }
}

mutation { update_strategy(strategy: { id: "str_123", name: "Updated" }) { success data { id } } }
mutation { delete_strategy(id: "str_123") { success } }
mutation { link_copiers(strategy_id: "str_123", copier_ids: ["cop_456"]) { success linked_count } }

Copiers

mutation {
  create_copier(copier: {
    exchange_account_id: "exc_456"
    strategy_id: "str_123"
    name: "My Copier"
  }) { success data { id name } }
}

mutation { update_copier(copier: { id: "cop_123", name: "Updated" }) { success } }
mutation { delete_copier(id: "cop_123") { success } }
mutation { toggle_copier_status(id: "cop_123") { success data { id is_active } } }

Trades

mutation {
  create_trade(trade: {
    exchange_account_id: "exc_123"
    trade_pair_id: "tp_btcusdt"
    type: "LIMIT"
    side: "BUY"
    price: 50000
    amount: 0.1
  }) { success data { id status } }
}

mutation { update_trade(trade: { id: "trd_123", status: "CANCELLED" }) { success data { id status } } }
mutation { delete_trade(id: "trd_123") { success } }
mutation { cancel_trade(id: "trd_123") { success data { id status } } }

Bulk & maintenance

Higher-volume and housekeeping operations for trade ingestion and the partition store:

Mutation	Purpose
bulk_create_trades(trades: [BulkTradeInput!]!)	Insert many trades
bulk_update_trades(trades: [TradeUpdateInput!]!)	Update many trades
bulk_delete_trades(ids: [String!]!)	Delete many trades
import_trades_from_csv(csvData, mappings)	Import trades from CSV
import_trades_from_exchange(exchangeAccountId, startDate, endDate)	Backfill from an exchange
archive_old_trades(cutoffDate)	Archive trades before a date
sync_trade_with_exchange(id)	Reconcile one trade against the exchange
recalculate_trade_metrics(tradeIds, dateRange)	Recompute analytics
optimize_partition(year, month) / rebuild_indexes	Partition maintenance

User Settings

mutation { update_user_setting(user_setting: { key: "theme", value: "dark" }) { success data { key value } } }
mutation { delete_user_setting(id: "setting_123") { success } }

Notifications

mutation { delete_notification(id: "notif_123") { success } }

Withdrawals

mutation { create_withdraw(withdraw: { amount: 100, wallet_address: "0x..." }) { success data { id } } }
mutation { update_withdraw(withdraw: { id: "wd_123", status: "CANCELLED" }) { success data { id } } }
mutation { cancel_withdraw(id: "wd_123") { success data { id } } }
mutation { delete_withdraw(id: "wd_123") { success } }

API Keys

mutation { create_api_key(input: { name: "ci-bot", env: "live" }) { success data { id secret } } }
mutation { rotate_api_key(id: "key_123") { success data { id secret } } }
mutation { revoke_api_key(id: "key_123", reason: "rotated") { success } }

CLI Identity

mutation {
  register_cli_identity(
    public_key: "02ab..."
    signature_over_challenge: "..."
    challenge_id: "chal_123"
    label: "my-laptop"
  ) { id account_id label }
}

Waitlist

mutation {
  joinWaitlist(email: "user@example.com", recaptcha_token: "token", source: "docs") {
    success
    message
  }
}

Admin

Active admin mutations (require a system-admin identity, authorized per-resolver via requireAdmin; all write to the AuditLog). These back the tokenbot-admin CLI:

mutation { adminUpdateUser(user_id: "user_123", input: { is_active: false }) { id is_active } }
mutation { adminBanUser(user_id: "user_123", reason: "TOS violation") { id is_active } }
mutation { adminBulkUserAction(input: { user_ids: ["user_1", "user_2"], action: BAN, reason: "spam" }) { success affected } }

---

Deprecated (dashboard-era) mutations

Still resolvable for backward compatibility, but @deprecated (web dashboard sunset) and slated for removal in v2.0. The password/OAuth/passkey login flows below are legacy — new clients should authenticate with the CLI signed-request scheme or a REST API key:

• Auth: register, login, verify_2fa_code, refresh_token, logout, logout_all, google_auth, x_auth, apple_auth, telegram_auth, verify_email, forgot_password, reset_password, generate_2fa, enable_2fa, disable_2fa
• User: change_email, confirm_email_change, change_password, login_with_telegram, login_with_discord
• Organizations: create_organization, update_organization, delete_organization, invite_member, update_member_role, remove_member, switch_organization
• Passkeys: generatePasskeyRegistrationChallenge, registerPasskey, generatePasskeyLoginChallenge, loginWithPasskey, deletePasskey, renamePasskey
• Onboarding: updateOnboardingStatus, completeOnboarding, resetOnboarding, trackOnboardingEvent
• Admin (legacy): adminResetUserPassword, adminChangeUserEmail, adminResetUser2FA, adminDeactivateUser, adminReactivateUser, adminToggleSystemAdmin, adminEnableApiKey, adminDisableApiKey
• CRUD seed data: create_user_reward / update_user_reward / delete_user_reward, create_reward_type / update_reward_type / delete_reward_type, create_trade_pair / update_trade_pair / delete_trade_pair, create_supported_exchange / update_supported_exchange / delete_supported_exchange, create_notification / update_notification, create_user_setting