Tables Reference

Complete column reference for all Nexgent database tables.

users

User accounts for authentication.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`email`	`varchar(255)`	UNIQUE, NOT NULL	User email address
`password_hash`	`varchar(255)`	NULLABLE	bcrypt password hash
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Account creation time
`failed_login_attempts`	`int`	NOT NULL, DEFAULT 0	Failed login counter
`locked_until`	`timestamptz`	NULLABLE	Account lockout expiry

Indexes: email (unique)

api_keys

API keys for programmatic access.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`user_id`	`uuid`	FK → users, NOT NULL	Owner user
`name`	`varchar(100)`	NOT NULL	Key display name
`key_hash`	`text`	UNIQUE, NOT NULL	bcrypt hash of key
`key_prefix`	`varchar(12)`	NOT NULL	First 12 chars for identification
`scopes`	`text[]`	NOT NULL, DEFAULT []	Permission scopes
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Creation time

Indexes: user_id, key_hash (unique)

The raw API key is only shown once at creation. Only the hash is stored.

agents

Trading agents created by users.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`user_id`	`uuid`	FK → users, NOT NULL	Owner user
`name`	`varchar(255)`	NOT NULL	Agent display name
`trading_mode`	`varchar(20)`	NOT NULL, DEFAULT 'simulation'	'simulation' or 'live'
`automated_trading_simulation`	`boolean`	NOT NULL, DEFAULT true	Auto-trade in simulation
`automated_trading_live`	`boolean`	NOT NULL, DEFAULT true	Auto-trade in live
`trading_config`	`jsonb`	NULLABLE	AgentTradingConfig JSON
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Creation time
`updated_at`	`timestamptz`	NOT NULL	Last update time

Indexes: user_id

agent_wallets

Wallet assignments for agents. Private keys are never stored.

Column	Type	Constraints	Description
`wallet_address`	`varchar(44)`	PK	Solana wallet address
`agent_id`	`uuid`	FK → agents, NOT NULL	Assigned agent
`wallet_type`	`varchar(20)`	NOT NULL	'simulation' or 'live'
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Assignment time
`updated_at`	`timestamptz`	NOT NULL	Last update time

Indexes: agent_id

Unique Constraints: (agent_id, wallet_type) - One wallet per mode per agent

agent_balances

Token balances per wallet.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`agent_id`	`uuid`	FK → agents, NOT NULL	Owner agent
`wallet_address`	`varchar(44)`	FK → agent_wallets, NOT NULL	Wallet address
`token_address`	`varchar(255)`	NOT NULL	Token mint address
`token_symbol`	`varchar(20)`	NOT NULL	Token symbol (e.g., SOL)
`balance`	`text`	NOT NULL	Balance as string (arbitrary precision)
`last_updated`	`timestamptz`	NOT NULL	Last balance update

Indexes: agent_id, wallet_address, (agent_id, wallet_address), token_address

Unique Constraints: (wallet_address, token_address) - One balance per token per wallet

💡

Balance is stored as string to support arbitrary precision for all token types.

agent_positions

Open trading positions with stop loss and take-profit state.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`agent_id`	`uuid`	FK → agents, NOT NULL	Owner agent
`wallet_address`	`varchar(44)`	FK → agent_wallets, NOT NULL	Wallet address
`token_address`	`varchar(255)`	NOT NULL	Token mint address
`token_symbol`	`varchar(20)`	NOT NULL	Token symbol
`purchase_transaction_id`	`uuid`	FK → agent_transactions, UNIQUE	Initial purchase
`purchase_price`	`decimal(30,18)`	NOT NULL	Price at purchase (SOL per token)
`purchase_amount`	`decimal(30,18)`	NOT NULL	Token amount purchased (original)
`remaining_amount`	`decimal(30,18)`	NULLABLE	Tokens remaining after take-profit
`current_stop_loss_percentage`	`decimal(5,2)`	NULLABLE	Active stop loss %
`peak_price`	`decimal(30,18)`	NULLABLE	Highest price seen
`lowest_price`	`decimal(30,18)`	NULLABLE	Lowest price seen
`last_stop_loss_update`	`timestamptz`	NULLABLE	Last SL evaluation
`dca_count`	`int`	NOT NULL, DEFAULT 0	Number of DCA buys
`dca_transaction_ids`	`uuid[]`	NOT NULL, DEFAULT []	DCA transaction refs
`last_dca_time`	`timestamptz`	NULLABLE	Last DCA execution
`take_profit_levels_hit`	`int`	NOT NULL, DEFAULT 0	Number of TP levels triggered
`take_profit_transaction_ids`	`text[]`	NOT NULL, DEFAULT []	TP sale transaction refs
`last_take_profit_time`	`timestamptz`	NULLABLE	Last TP execution
`moon_bag_activated`	`boolean`	NOT NULL, DEFAULT false	Moon bag set aside
`moon_bag_amount`	`decimal(30,18)`	NULLABLE	Tokens reserved as moon bag
`realized_profit_sol`	`decimal(20,8)`	NULLABLE	Cumulative profit from TP sales
`total_invested_sol`	`decimal(20,8)`	NOT NULL, DEFAULT 0	Total SOL invested
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Position open time
`updated_at`	`timestamptz`	NOT NULL	Last update time

Indexes: agent_id, token_address, (agent_id, wallet_address), purchase_transaction_id

Unique Constraints: (agent_id, wallet_address, token_address) - One position per token per wallet

Take-Profit Fields: remaining_amount tracks tokens after partial sales, take_profit_levels_hit counts executed levels, and realized_profit_sol accumulates profit from take-profit sales. When take-profit is enabled, remaining_amount may be less than purchase_amount.

agent_transactions

All transaction records (deposits, withdrawals, swaps, burns).

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`agent_id`	`uuid`	FK → agents, NOT NULL	Owner agent
`wallet_address`	`varchar(44)`	FK → agent_wallets, NULLABLE	Wallet address
`transaction_type`	`enum`	NOT NULL	DEPOSIT, WITHDRAWAL, SWAP, BURN
`transaction_value_usd`	`decimal(20,8)`	NOT NULL	USD value at time
`transaction_time`	`timestamptz`	NOT NULL	Execution time
`destination_address`	`varchar(255)`	NULLABLE	For withdrawals
`signal_id`	`int`	FK → trading_signals, NULLABLE	Triggering signal
`fees`	`decimal(20,8)`	NULLABLE	Transaction fees
`routes`	`jsonb`	NULLABLE	Jupiter route info
`input_mint`	`varchar(255)`	NULLABLE	Input token address
`input_symbol`	`varchar(20)`	NULLABLE	Input token symbol
`input_amount`	`decimal(30,18)`	NULLABLE	Input amount
`input_price`	`decimal(30,18)`	NULLABLE	Input price
`output_mint`	`varchar(255)`	NULLABLE	Output token address
`output_symbol`	`varchar(20)`	NULLABLE	Output token symbol
`output_amount`	`decimal(30,18)`	NULLABLE	Output amount
`output_price`	`decimal(30,18)`	NULLABLE	Output price
`slippage`	`decimal(10,4)`	NULLABLE	Actual slippage
`price_impact`	`decimal(10,4)`	NULLABLE	Price impact
`is_dca`	`boolean`	NOT NULL, DEFAULT false	Is DCA transaction
`is_take_profit`	`boolean`	NOT NULL, DEFAULT false	Is take-profit sale
`transaction_hash`	`varchar(255)`	NULLABLE	On-chain tx hash
`swap_payload`	`jsonb`	NULLABLE	Full Jupiter response
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Record creation
`updated_at`	`timestamptz`	NOT NULL	Last update

Indexes: agent_id, wallet_address, (agent_id, wallet_address), transaction_type, transaction_time, signal_id, (agent_id, transaction_time), (agent_id, transaction_type)

agent_historical_swaps

Completed trade records with profit/loss.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`agent_id`	`uuid`	FK → agents, NOT NULL	Owner agent
`wallet_address`	`varchar(44)`	FK → agent_wallets, NULLABLE	Wallet address
`token_address`	`varchar(255)`	NOT NULL	Token mint address
`token_symbol`	`varchar(20)`	NOT NULL	Token symbol
`amount`	`decimal(30,18)`	NOT NULL	Token amount traded (original position)
`purchase_price`	`decimal(30,18)`	NOT NULL	Buy price (weighted average)
`sale_price`	`decimal(30,18)`	NOT NULL	Sell price (effective average if take-profit)
`change_percent`	`decimal(10,4)`	NOT NULL	% return (vs original cost basis)
`profit_loss_usd`	`decimal(20,8)`	NOT NULL	Total P/L in USD (includes take-profit)
`profit_loss_sol`	`decimal(20,8)`	NOT NULL	Total P/L in SOL (includes take-profit)
`purchase_time`	`timestamptz`	NOT NULL	Buy time
`sale_time`	`timestamptz`	NOT NULL	Final sale time
`purchase_transaction_id`	`uuid`	FK → agent_transactions, NULLABLE	Buy transaction
`sale_transaction_id`	`uuid`	FK → agent_transactions, NULLABLE	Final sell transaction
`signal_id`	`int`	FK → trading_signals, NULLABLE	Original signal
`close_reason`	`varchar(20)`	NULLABLE	stop_loss, stale_trade, manual, take_profit
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Record creation

Indexes: agent_id, wallet_address, (agent_id, wallet_address), token_address, signal_id, purchase_transaction_id, sale_transaction_id, purchase_time, sale_time, (agent_id, token_address), (agent_id, purchase_time), (agent_id, sale_time), (agent_id, created_at), (agent_id, signal_id)

Positions with Take-Profit: For positions that had take-profit sales, amount is the original position size, sale_price is the effective average across all sales (take-profit + final close), and profit_loss_sol includes realized profit from all sales. The close_reason may be take_profit if the final close was triggered by take-profit completing.

agent_balance_snapshots

Hourly portfolio snapshots for charting.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`agent_id`	`uuid`	FK → agents, NOT NULL	Owner agent
`wallet_address`	`varchar(44)`	FK → agent_wallets, NOT NULL	Wallet address
`snapshot_timestamp`	`timestamptz`	NOT NULL	Snapshot time (hourly)
`portfolio_balance_sol`	`decimal(20,8)`	NOT NULL	Total portfolio in SOL
`sol_balance`	`decimal(20,8)`	NOT NULL	SOL balance only
`positions_value_sol`	`decimal(20,8)`	NOT NULL	Open positions value
`unrealized_pnl_sol`	`decimal(20,8)`	NOT NULL	Unrealized P/L
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Record creation
`updated_at`	`timestamptz`	NOT NULL	Last update

Indexes: (agent_id, wallet_address, snapshot_timestamp), wallet_address, snapshot_timestamp

Unique Constraints: (agent_id, wallet_address, snapshot_timestamp) - One snapshot per hour per wallet

trading_signals

Trading signals from external sources.

Column	Type	Constraints	Description
`id`	`serial`	PK	Auto-increment ID
`token_address`	`varchar(255)`	NOT NULL	Token mint address
`symbol`	`varchar(50)`	NULLABLE	Token symbol
`signal_type`	`varchar(50)`	NOT NULL	Signal type (e.g., 'buy')
`activation_reason`	`text`	NULLABLE	Why signal was created
`signal_strength`	`int`	NOT NULL	Strength 1-5
`source`	`varchar(100)`	NULLABLE	Signal source
`created_at`	`timestamptz`	NOT NULL, DEFAULT now()	Signal creation time
`updated_at`	`timestamptz`	NOT NULL	Last update

Indexes: token_address, signal_type, created_at

signal_executions

Signal processing status per agent.

Column	Type	Constraints	Description
`id`	`uuid`	PK	Unique identifier
`signal_id`	`int`	FK → trading_signals, NOT NULL	Signal reference
`agent_id`	`uuid`	FK → agents, NOT NULL	Agent reference
`status`	`varchar(20)`	NOT NULL	success, failed, skipped
`transaction_id`	`uuid`	FK → agent_transactions, NULLABLE	Resulting transaction
`error`	`text`	NULLABLE	Error message if failed
`executed_at`	`timestamptz`	NOT NULL, DEFAULT now()	Execution time

Indexes: signal_id, agent_id

Unique Constraints: (signal_id, agent_id) - One execution per agent per signal

Enums

TransactionType

CREATE TYPE "TransactionType" AS ENUM (
  'DEPOSIT',
  'WITHDRAWAL',
  'SWAP',
  'BURN'
);

Schema & ERD Migrations