Skip to content

API_ENDPOINTS.md

Latest commit

 

History

History
1203 lines (829 loc) · 44.2 KB

API_ENDPOINTS.md

File metadata and controls

1203 lines (829 loc) · 44.2 KB

LaunchAgencyBot Web UI - API Reference

Document Summary

Complete API reference for 60+ FastAPI endpoints organized by functional module. Includes request/response schemas, parameters, status codes, and critical notes.

Related Documentation:

Table of Contents

Quick Reference

Base Configuration

Property Value
Base URL http://127.0.0.1:8000
Protocol HTTP (HTTPS for production)
Content-Type application/json
Response Format JSON
Authentication None (development mode)

Server Startup: See GETTING_STARTED.md

Key Features

  • Orchestrator architecture with dependency injection
  • Pydantic v2 validation for all requests/responses
  • Consistent error handling with sanitized messages
  • Async/await throughout for performance

Common Patterns

Response Structure

Type Fields Example
Success status, success, message, timestamp {status: 200, success: true, message: "OK", timestamp: "2025-10-01T12:34:56Z"}
Error status, success, error, timestamp {status: 400, success: false, error: "Invalid parameter", timestamp: "..."}
Validation Error detail {detail: "Validation failed: field_name is required"}

Note: Domain-specific responses extend base structure with additional data fields.

Pagination

Parameter Type Description
page int 1-based page number (default: 1)
limit int Items per page (default varies: 20-500)

Response fields: items[], total, page, limit, total_pages, has_next, has_prev

Cache Control

Dynamic endpoints: Cache-Control: no-cache, no-store, must-revalidate

Master Endpoint Reference

Module GET POST DELETE PUT PATCH
Memecoin Ops /pending, /approved, /generated /approve/{addr}, /degrade/{addr}, /generated/{uuid}/ai-edit /pending/{addr}, /approved/{addr}, /generated/{uuid} /generated/{uuid} /generated/{uuid}
Database /search, /memecoins /memecoins/{addr}/ai-edit /memecoins/{addr} /memecoins/{addr} /memecoins/{addr}
Wallets /{address} /create, /generate, /{address}/refresh /{address} /{address} -
Funding /pending, /{fund_id}, /execution/status /create, /execution/toggle /{fund_id} - -
Launch Config /launches, /execution/status /launches, /execution/toggle /launches/{id} /launches/{id} -
Launches /available, /{launch_id} /create, /{launch_id}/execute /{launch_id} - -
Generation /tags, /status/{sid}, /results/{sid}, /sessions/stats /create, /session/{sid}/retry - - -
Trends /stats, /, /{trend_id}, /detection/status /detection/toggle - - -

Memecoin Operations

Module: src/web_ui/api/memecoin_routes.py | Orchestrator: MemeStorageOrchestrator, GenerationOrchestrator

Filesystem-based memecoin storage with atomic operations and cache management for pending, approved, and AI-generated memecoins.

Memecoin List Operations

Standard List Parameters:

Param Type Default Notes
page int 1 1-based page number (Min: 1)
limit int 100 Items per page (Min: 1, Max: 500)
search string null Search in tags, name, ticker, description

Standard List Response: {memecoins: Array<Memecoin>, total, page, limit, total_pages, has_next, has_prev}

Memecoin schema: {token_name, ticker, token_address, description, tags[], image_path, image_base64, creation_date, has_image, image_caption, tags_categories[]}

Endpoints:

  • GET /api/memecoins/pending - List pending memecoins awaiting approval | Status: 200, 500
  • GET /api/memecoins/approved - List approved memecoins ready for vector DB insertion | Status: 200, 500

POST /api/memecoins/approve/{token_address}

Atomically move pending memecoin to approved collection. Automatic cleanup on failure.

Param Type Location Notes
token_address string path Solana mint address

Response: {success: bool, message: string, status: int, timestamp: string} Status: 200, 404 (not found), 500 (file operation failed)

DELETE /api/memecoins/pending/{token_address} & /approved/{token_address}

Permanently delete memecoin. Response: {success, message, status, timestamp} Status: 200, 404, 500

POST /api/memecoins/degrade/{token_address}

Move memecoin from vector DB back to approved for reprocessing. AI-generated captions removed (regenerated on re-insertion), metadata and image preserved.

Response: {success: bool, message: string, status: int, timestamp: string} Status: 200, 404 (not found in DB), 500

GET /api/memecoins/pending/{token_address} & /approved/{token_address}

Retrieve specific memecoin by token address. Both return: Memecoin object with Base64 image.

Status: 200, 404, 500

GET /api/memecoins/image/{token_address}

Retrieve raw image data. Binary image response (cacheable 1 hour).

Param Type Location Default Options
token_address string path - -
source string query 'approved' 'pending', 'approved'

Response: Binary image data (Content-Type: image/jpeg) Status: 200, 404, 500

POST /api/memecoins/refresh-cache

Force refresh of all cached memecoin data.

Response: {success: bool, message: string, pending_cached: int, approved_cached: int} Status: 200, 500

Generated Memecoin Operations

Standard Parameters:

Param Type Default Range
page int 1 -
limit int 20 1-100

GeneratedMemecoin schema: {uuid, token_name, ticker, description, image_path, generation_timestamp, selected_for_launch, rag_context_count}

Endpoints:

  • GET /api/memecoins/generated - List AI-generated memecoins | Status: 200, 500
  • GET /api/memecoins/generated/{uuid} - Retrieve specific generated memecoin | Status: 200, 404, 500
  • PUT /api/memecoins/generated/{uuid} - Update metadata (partial updates supported, image immutable) | Status: 200, 404, 500, 503
  • DELETE /api/memecoins/generated/{uuid} - Permanently delete generated memecoin | Status: 200, 404, 500
  • POST /api/memecoins/generated/{uuid}/ai-edit - Generate AI-powered edit proposal | Status: 200, 400, 404, 500
  • PATCH /api/memecoins/generated/{uuid} - Accept and apply edit proposal | Status: 200, 400, 500

PUT Request: {name?: string, ticker?: string, description?: string, tags?: string[]}

Generated Memecoin AI Edit Workflow

AI-powered editing for generated memecoins using feedback-driven proposal system with 5-minute cache.

POST /api/memecoins/generated/{uuid}/ai-edit

Generate an AI-powered edit proposal based on user feedback.

Flow:

  1. User provides feedback about what to change
  2. AI analyzes feedback and determines affected fields
  3. Retrieves context from vector DB if needed (for logos, entities)
  4. Regenerates affected metadata and/or image
  5. Returns proposal with UUID for review (cached 5 minutes)

Request: {feedback: string, current_metadata?: {name, ticker, description, tags}}

Field Type Required Notes
feedback string Yes 1-2000 chars, describes desired changes
current_metadata object No If provided, used as baseline. If omitted, loads from storage

Response: {status, success, message, proposal_uuid, proposal}

Field Type Notes
proposal_uuid string UUID for cached proposal (5-min TTL)
proposal object Edit proposal data with affected fields
proposal.name string New token name (if changed)
proposal.ticker string New ticker symbol (if changed)
proposal.description string New description (if changed)
proposal.image_regenerated boolean True if image was regenerated

Status: 200 (success), 400 (invalid feedback/metadata), 404 (memecoin not found), 500 (generation failed)

Intelligent Features:

  • Automatic decision of what needs regeneration
  • Context retrieval for accurate entity representation
  • Conditional image regeneration with visual references
  • Targeted metadata updates (only affected fields)

Feedback Examples:

  • "Make the dog blue instead of brown"
  • "Fix the BNB logo - it should be the official one"
  • "Change name to something with wordplay"
  • "Wrong art style - should be pixel art"

Error Scenarios:

  • 400: Empty/invalid feedback, malformed metadata
  • 404: Generated memecoin UUID not found
  • 500: AI generation service failure, vector DB unavailable

PATCH /api/memecoins/generated/{uuid}

Accept and apply edit proposal to generated memecoin.

Flow:

  1. Retrieves proposal from cache (or uses provided edited_proposal)
  2. Validates proposal hasn't expired (5-minute TTL)
  3. Applies all changes in-place (same UUID, atomic update)
  4. Saves to storage
  5. Removes proposal from cache

Request: {proposal_uuid: string, edited_proposal?: object}

Field Type Required Notes
proposal_uuid string Yes UUID from POST ai-edit response
edited_proposal object No Manually edited proposal overrides cached version

Response: {status, success, message}

Status: 200 (success), 400 (proposal expired/not found/invalid UUID), 500 (storage failure)

What Gets Updated:

  • Token name (if changed in proposal)
  • Ticker (if changed in proposal)
  • Description (if changed in proposal)
  • Image (if regenerated in proposal)

Optional Manual Editing:

  • You can provide edited_proposal to override cached version
  • Useful for fine-tuning the AI-generated proposal before applying

Error Scenarios:

  • 400: Proposal UUID not found in cache (expired or invalid)
  • 400: Proposal expired (5-minute TTL exceeded)
  • 400: Malformed edited_proposal structure
  • 500: Failed to save updated memecoin

Use Cases:

  • User requests color/style changes via natural language
  • Fix entity representation issues (wrong logo, character)
  • Adjust art style or visual attributes
  • Refine metadata based on user preferences

POST /api/memecoins/generated/{uuid}/select

Toggle selection status for launch. Param selected defaults to true.

Response: {success: bool, message: string, status: int, timestamp: string} Status: 200, 404, 500

Database Operations

Module: src/web_ui/api/database_routes.py | Database: ChromaDB 5-collection architecture

Vector database management for memecoin RAG system. Uses multi-embedding architecture: image CLIP embeddings + 4 caption types (entity, context, visual, emotions).

Database Search Operations

GET /api/database/search - Search memecoins by tags with fuzzy matching

Param Type Required Default Notes
tags string Yes - Comma/space separated (matches ANY)
page int No 1 Min: 1
limit int No 200 Min: 1

Status: 200, 400, 500

GET /api/database/memecoins - List all memecoins from vector DB with optional tag filtering

Param Type Required Default Notes
page int No 1 -
limit int No 200 No maximum
search string No null Tag search query

Status: 200, 500, 503 (ChromaDB compaction errors; returns 503 with retry suggestion on HNSW segment errors)

Response (both): MemecoinListResponse (standard pagination schema)

Database Destructive Operations

DELETE /api/database/memecoins/{token_address} - Delete memecoin from vector DB and filesystem

⚠️ Irreversible: Removes from all 5 ChromaDB collections + image/metadata files

Status: 200, 404, 500

POST /api/database/admin/clear - Clear entire database (development/testing only)

⚠️ WARNING: Destructive and irreversible. Use only in development with backups.

Status: 200, 500

Response (both): {status, success, message} (clear includes record count)

Database Memecoin AI Edit Workflow

AI-powered editing for database memecoins with immutability rules and CLIP embedding regeneration.

⚠️ CRITICAL: Field Restrictions Database memecoins are on-chain tokens with immutable blockchain metadata:

  • ✅ ALLOWED: tags, caption_structured (user-managed metadata)
  • ❌ FORBIDDEN: token_name, ticker, description (on-chain immutable data)

POST /api/database/memecoins/{token_address}/ai-edit

Generate an AI-powered edit proposal based on user feedback.

Flow:

  1. User provides feedback about what to change
  2. LLM analyzes feedback and determines affected fields
  3. Regenerates only the affected metadata/captions
  4. Returns proposal with UUID for review (cached 5 minutes)

Request: {feedback: string}

Field Type Required Notes
feedback string Yes 1-2000 chars, describes desired changes

Response: {status, success, message, proposal_uuid, proposal}

Field Type Notes
proposal_uuid string UUID for cached proposal (5-min TTL)
proposal object Edit proposal data with affected fields
proposal.tags string[] New tags (if changed)
proposal.caption_structured object New caption structure (if changed)
proposal.caption_structured.entity string Entity caption part
proposal.caption_structured.context string Context caption part
proposal.caption_structured.visual string Visual caption part
proposal.caption_structured.emotions string Emotions caption part

Status: 200 (success), 400 (invalid feedback), 404 (memecoin not found), 500 (generation failed)

Feedback Examples:

  • "The entity should be a dog, not a cat"
  • "Wrong visual style - it's pixel art, not realistic"
  • "Add gaming and retro tags"
  • "Change name to CryptoKitty" ⚠️ Will fail (immutable field)

Error Scenarios:

  • 400: Empty/invalid feedback, feedback requests immutable field changes
  • 404: Memecoin token address not found in vector DB
  • 500: AI generation service failure, vector DB unavailable

PATCH /api/database/memecoins/{token_address}

Accept and apply edit proposal to vector database memecoin.

Flow:

  1. Retrieves proposal from cache (or uses provided edited_proposal)
  2. Validates proposal hasn't expired (5-minute TTL)
  3. Regenerates caption embeddings for modified parts
  4. Atomically updates all 5 vector DB collections
  5. Removes proposal from cache

Request: {proposal_uuid: string, edited_proposal?: object}

Field Type Required Notes
proposal_uuid string Yes UUID from POST ai-edit response
edited_proposal object No Manually edited proposal overrides cached version

Response: {status, success, message}

Status: 200 (success), 400 (proposal expired/not found/invalid), 500 (update failed)

What Gets Updated:

  • Image collection: Metadata only (image unchanged)
  • Entity collection: Metadata + new CLIP embedding (if caption changed)
  • Context collection: Metadata + new CLIP embedding (if caption changed)
  • Visual collection: Metadata + new CLIP embedding (if caption changed)
  • Emotions collection: Metadata + new CLIP embedding (if caption changed)

CLIP Embedding Regeneration:

  • Triggered when caption_structured fields change
  • Updates all 5 vector DB collections
  • May take 2-5 seconds to complete

Optional Manual Editing:

  • You can provide edited_proposal to override cached version
  • Useful for fine-tuning the AI-generated proposal before applying

Error Scenarios:

  • 400: Proposal UUID not found in cache (expired or invalid)
  • 400: Proposal expired (5-minute TTL exceeded)
  • 400: Malformed edited_proposal structure
  • 500: Failed to update vector database or regenerate embeddings

PUT /api/database/memecoins/{token_address}

Direct update database memecoin without AI proposal (no cache, immediate update).

⚠️ CRITICAL: Field Restrictions Database memecoins are on-chain tokens. Only user-managed metadata can be edited:

  • ✅ ALLOWED: tags, caption_structured
  • ❌ FORBIDDEN: token_name, ticker, description (will return 400 error)

Request: {tags?: string[], caption_structured?: object}

Field Type Required Notes
tags string[] No New tags (max 20)
caption_structured object No New caption structure (4 parts)
caption_structured.entity string No Entity caption part
caption_structured.context string No Context caption part
caption_structured.visual string No Visual caption part
caption_structured.emotions string No Emotions caption part

⚠️ FORBIDDEN FIELDS (will cause 400 Bad Request):

  • token_name - Immutable on-chain metadata
  • ticker - Immutable on-chain metadata
  • description - Immutable on-chain metadata

Response: {status, success, message, embeddings_regenerated}

Field Type Notes
embeddings_regenerated boolean True if CLIP embeddings were regenerated

Status: 200 (success), 400 (immutable field provided/no fields/invalid), 404 (not found), 500 (update failed)

Embedding Regeneration:

  • Automatically triggered when caption_structured fields change
  • Updates all 5 vector DB collections
  • May take 2-5 seconds to complete

Comparison: PUT vs AI Edit (POST + PATCH)

Feature PUT (Direct) AI Edit (POST + PATCH)
Input New values directly Natural language feedback
Workflow Single step Two steps (propose → accept)
Cache No cache 5-minute proposal cache
AI Analysis No Yes (determines affected fields)
Use Case Quick manual edits Natural language refinement

Error Scenarios:

  • 400: Forbidden field provided (token_name/ticker/description)
  • 400: No fields provided in request
  • 400: Invalid caption_structured format
  • 404: Memecoin not found in vector database
  • 500: Failed to update vector database or regenerate embeddings

Use Cases:

  • Tag updates and refinements
  • Caption corrections and improvements
  • NOT for name/ticker/description changes (use generated memecoins for that)

Wallet Management

Module: src/web_ui/api/wallet_management_routes.py | Orchestrator: WalletsOrchestrator

Solana wallet portfolio management with Firebase cache and blockchain refresh. Status values: FRESH, UNFUNDED, FUNDED, INACTIVE.

Wallet CRUD Operations

Wallet schema: {wallet_address, name, status, sol_balance, last_refresh, token_count, created_at}

Status values: FRESH, UNFUNDED, FUNDED, INACTIVE

Endpoints:

  • GET /api/wallets - List all managed wallets (Firebase cache, ~100-300ms, no blockchain queries) | Response: {wallets: Array<Wallet>, total_wallets, total_sol_balance} | Status: 200, 500
  • GET /api/wallets/{wallet_address} - Detailed wallet info with portfolio and funding history | Response includes: portfolio.tokens[], portfolio.nfts[], funding_history[] | Status: 200, 404, 500
  • POST /api/wallets - Register new wallet with initial blockchain verification | Request: {wallet_address, name} | Status: 200, 400 (invalid), 409 (duplicate), 500
  • PUT /api/wallets/{wallet_address} - Update metadata (cache-only, no blockchain refresh) | Request: {status?: WalletStatus, name?: string} | Status: 200, 404, 500
  • DELETE /api/wallets/{wallet_address} - Remove from management (cascade deletes funding/configs, blockchain wallet unaffected) | Status: 200, 404, 500

Response (single wallet): Wallet object

Wallet Generation & Refresh

POST /api/wallets/generate

Generate a new Solana wallet keypair (two-step flow for security).

⚠️ SECURITY: Two-Step Wallet Flow

  1. Step 1 (this endpoint): Generate keypair → Returns address + private key
  2. Step 2 (manual): User saves private key securely
  3. Step 3: POST /api/wallets → Register wallet in system

Why Two Steps:

  • User can regenerate if needed without cluttering database
  • Forces explicit private key handling
  • Prevents accidental wallet loss

Request: No body required

Response: {status, success, message, wallet_address, private_key}

Field Type Notes
wallet_address string Base58-encoded Solana address (43-44 chars)
private_key string Base58-encoded private key (87-88 chars)

⚠️ CRITICAL: Private Key Security

  • Private key returned ONCE and never stored
  • User MUST save immediately
  • Lost private key = lost wallet access forever
  • Private key not logged (security best practice)

Status: 200 (success), 500 (generation failed)

Use Cases:

  • Create new wallets for launches
  • Generate dev wallets for testing
  • Replace lost/compromised wallets

Error Scenarios:

  • 500: Keypair generation failure (rare, cryptographic error)

Example Flow:

// Step 1: Generate keypair
const response = await fetch('/api/wallets/generate', {method: 'POST'});
const {wallet_address, private_key} = await response.json();

// Step 2: User saves private_key securely (NOT in code!)

// Step 3: Register wallet
await fetch('/api/wallets', {
  method: 'POST',
  body: JSON.stringify({
    wallet_address,
    name: 'My Dev Wallet'
  })
});

POST /api/wallets/{wallet_address}/refresh

Refresh wallet from Solana blockchain (live data with cache update).

Process:

  1. Queries Solana RPC for current blockchain state
  2. Updates SOL balance and token count
  3. Updates wallet status (UNFUNDED if 0 SOL, FUNDED if >= 0.25 SOL)
  4. Saves to Firebase cache
  5. Returns updated wallet data

Request: No body required

Path Parameters:

Param Type Notes
wallet_address string Base58-encoded Solana address to refresh

Response: {status, success, message, wallet}

Field Type Notes
wallet object Full wallet object with updated blockchain data
wallet.sol_balance number Current SOL balance (from blockchain)
wallet.token_count number Number of SPL tokens (from blockchain)
wallet.status string Auto-updated: UNFUNDED/FUNDED based on balance
wallet.last_refresh string ISO timestamp of this refresh

Status: 200 (success), 404 (wallet not found), 500 (server error), 503 (RPC unavailable)

Performance:

  • Latency: ~2-4 seconds (blockchain query time)
  • Cache: Updates Firebase cache on success
  • RPC: Single blockchain query per refresh

Use Cases:

  • Verify wallet balance before launch
  • Check funding status after transfer
  • Update dashboard with live data
  • Monitor wallet activity

Error Scenarios:

  • 404: Wallet not registered in management system
  • 500: Firebase update failure
  • 503: Solana RPC unavailable or timeout

When to Use:

  • Use: Before critical operations (launch, funding check)
  • Use: After external transfers to verify balance
  • Avoid: Polling in tight loops (use cache via GET instead)

Best Practices:

  • Don't refresh more than once every 30 seconds
  • Use GET /api/wallets/{address} for cached data
  • Handle 503 gracefully (RPC downtime is temporary)

Funding Operations

Module: src/web_ui/api/funding_routes.py | Orchestrator: FundingOrchestrator

SOL funding scheduling, execution, and archival with CEX integration. Status values: PENDING, COMPLETED, FAILED.

Funding Lifecycle Operations

Status values: PENDING, COMPLETED, FAILED

Funding ID format: {uuid6}_{wallet_address}

Plan & Execute:

  • POST /api/funding/plan - Plan future SOL funding (0.1-10.0 SOL, scheduled timestamp required) | Request: {wallet_address, sol_amount, scheduled_timestamp} | Status: 201, 400, 404, 500
  • POST /api/funding/execute/{schedule_id} - Execute immediately (CEX/direct transfer, sets wallet to FUNDED if balance >= 0.25 SOL) | Response includes: transaction_signature, executed_at, new_balance, wallet_status | Status: 200, 400 (invalid state or execution failed), 404, 500

List & Query:

  • GET /api/funding/planned - List planned operations with optional status filter (PENDING/COMPLETED/FAILED) | Response: {operations: Array<FundingOp>, total, status_filter?} | Status: 200, 500
  • GET /api/funding/archived - List archived operations (limit default: 100) | Status: 200, 500

State Management:

  • DELETE /api/funding/{schedule_id} - Delete operation (PENDING/FAILED only, cannot delete COMPLETED/ARCHIVED) | Status: 200, 400, 404, 500
  • POST /api/funding/archive/{schedule_id} - Archive operation (COMPLETED/FAILED only) | Status: 200, 400, 404, 500
  • POST /api/funding/restore/{schedule_id} - Restore archived to PENDING | Status: 200, 404, 500

Funding Execution Control

Control automatic funding execution for cost management and operational control.

POST /api/funding/execution/toggle

Toggle automatic funding execution on/off.

Behavior:

  • If currently enabled → disables execution
  • If currently disabled → enables execution

When Enabled:

  • Scheduled funding operations execute automatically
  • Blockchain transactions occur on schedule

When Disabled:

  • No automatic execution
  • Manual execution via /execute/{schedule_id} still works
  • Use for maintenance windows or cost control

Request: No body required (toggle action)

Response: {status, success, message, execution_active, pending_operations}

Field Type Notes
execution_active boolean Current execution state after toggle
pending_operations integer Number of PENDING operations in queue

Status: 200 (success), 500 (server error)

Use Cases:

  • Cost management (pause automated transfers)
  • Maintenance windows
  • Testing configurations without execution
  • Emergency stop for issues

GET /api/funding/execution/status

Get current funding execution status and pending operations count.

Request: No parameters

Response: {status, success, message, execution_active, pending_operations}

Field Type Notes
execution_active boolean Whether automatic execution is enabled
pending_operations integer Number of PENDING operations in queue

Status: 200 (success), 500 (server error)

Use Cases:

  • Display toggle state in UI
  • Monitor execution status
  • Dashboard indicators
  • Pre-flight checks before scheduling

Launch Operations

Router: /api/launches | Module: src/web_ui/api/launch_routes.py | Orchestrator: LaunchOrchestrator

Manages memecoin launches on Solana via pump.fun with atomic CREATE+BUY transactions.

Launch Execution

POST /api/launches - Execute immediate memecoin launch on Solana blockchain

Atomic transaction (CREATE+ATA+BUY). Fixed supply: 1B tokens, 6 decimals. Requires wallet status READY and sufficient SOL.

Param Type Required Default Notes
network query string No devnet Options: devnet, mainnet

Request: {token_name, token_symbol, dev_wallet_address, dev_sol_amount, metadata: {description?, twitter?, telegram?, website?, image_url?}}

Response: {success, launch_id, token_name, token_symbol, token_mint, dev_wallet_address, transaction_signature, status, network, launched_at, pump_fun_url}

Status: 201, 400, 404, 500, 503

Launch Query Operations

Status values: SCHEDULED, COMPLETED, FAILED, CANCELLED

Endpoints:

  • GET /api/launches/history - Launch history with filters (wallet_address, status, limit default: 50, sorted newest first) | Response: {launches: Array<Launch>, total, filter} | Status: 200, 500
  • GET /api/launches/{launch_id} - Detailed launch info | Response includes: transaction_signature, network, metadata, associated_wallet, pump_fun_url | Status: 200, 404, 500

Launch Cancellation

DELETE /api/launches/{launch_id}

Cancel a pending launch operation before blockchain execution.

Cancellation Rules:

  • Can only cancel launches with status: READY, SCHEDULED
  • Cannot cancel: EXECUTING, COMPLETED, or already FAILED
  • Cancellation is permanent (cannot be undone)
  • Wallet status management simplified

Process:

  1. Retrieves launch record from Firebase
  2. Validates current status (must be READY or SCHEDULED)
  3. Updates status to FAILED
  4. Adds cancellation metadata (timestamp, reason)
  5. Stores execution status as CANCELLED in metadata

Path Parameters:

Param Type Notes
launch_id string Launch identifier from creation

Request: No body required

Response: {status, success, message}

Status: 200 (success), 400 (invalid state), 404 (launch not found), 500 (server error)

Status Transition:

  • ✅ READY → FAILED (CANCELLED)
  • ✅ SCHEDULED → FAILED (CANCELLED)
  • ❌ EXECUTING → Cannot cancel (blockchain tx in progress)
  • ❌ COMPLETED → Cannot cancel (already on-chain)
  • ❌ FAILED → Cannot cancel (already failed)

Error Scenarios:

  • 400: Launch not in cancelable state (EXECUTING/COMPLETED/FAILED)
  • 404: Launch ID not found in Firebase
  • 500: Firebase update failure

Use Cases:

  • Cancel launches before scheduled time
  • Remove launches with incorrect parameters
  • Emergency cancellation before execution
  • Clean up test launches

Metadata Added on Cancellation:

{
  "cancelled_at": 1698765432,
  "cancellation_reason": "manual_cancellation",
  "launch_status": "CANCELLED"
}

Best Practices:

  • Cancel as soon as error detected (don't wait for execution)
  • Check status before cancelling (avoid 400 errors)
  • Use for pre-execution cancellations only
  • Consider DELETE /api/launch-config/launches/{id} for configurations

Example Flow:

// 1. Check launch status
const launch = await fetch('/api/launches/abc123').then(r => r.json());

// 2. Verify cancelable
if (['READY', 'SCHEDULED'].includes(launch.launch_status)) {
  // 3. Cancel
  await fetch('/api/launches/abc123', {method: 'DELETE'});
  console.log('Launch cancelled successfully');
} else {
  console.log('Cannot cancel - status:', launch.launch_status);
}

Launch Configuration

Router: /api/launch-config | Module: src/web_ui/api/launch_config_routes.py | Orchestrator: LaunchConfigurationOrchestrator

Manages pre-launch planning with configuration CRUD, scheduling, and validation.

Launch Configuration CRUD

Launch types: DRAFT (minimal), COMPLETE (full) Status values: READY, SCHEDULED, LAUNCHING, LAUNCHED, FAILED, CANCELLED

List & Query:

  • GET /api/launch-config/launches - List configurations with filters (launch_type, status, limit default: 50) | Response includes: status_breakdown, counts | Status: 200, 500
  • GET /api/launch-config/launches/{launch_id} - Detailed configuration | Response includes all fields: launch_name, launch_type, metadata, meme_uuid, scheduled_for | Status: 200, 404, 500
  • GET /api/launch-config/statistics - Comprehensive statistics | Response: {total_configurations, by_type, by_status, ready_for_launch, scheduled_launches} | Status: 200, 500

Create & Update:

  • POST /api/launch-config/launches - Create new configuration (status auto-determined: READY if all fields present, DRAFT otherwise) | Request: {launch_name, launch_type, dev_wallet_address, dev_sol_amount, token_name?, token_symbol?, metadata?, meme_uuid?} | Status: 201, 400, 500
  • PUT /api/launch-config/launches/{launch_id} - Update with partial updates (automatic status recalculation) | Request: all fields optional | Status: 200, 404, 500
  • DELETE /api/launch-config/launches/{launch_id} - Delete configuration | Status: 200, 404, 500

Execution:

  • POST /api/launch-config/launches/{launch_id}/schedule - Schedule for future time (requires READY status, future timestamp, sufficient SOL) | Request: {scheduled_time: ISO8601} | Status: 200, 400, 404, 500
  • POST /api/launch-config/launches/{launch_id}/execute - Execute immediately (same process as POST /api/launches) | Response includes: token_mint, transaction_signature, pump_fun_url | Status: 200, 400, 404, 500, 503

Resource Lists:

  • GET /api/launch-config/memecoins/generated - Available generated memecoins (page default: 1, limit default: 20) | Response includes: selected_for_launch, already_configured flags | Status: 200, 500
  • GET /api/launch-config/wallets/available - Available wallets from registry | Response includes: is_ready, ready_for_launch counts | Status: 200, 500

Launch Execution Control

Control automatic launch execution for scheduled launches.

POST /api/launch-config/execution/toggle

Toggle automatic launch execution on/off.

Behavior:

  • If currently enabled → disables execution
  • If currently disabled → enables execution

When Enabled:

  • Scheduled launches execute automatically at their scheduled time
  • On-chain transactions occur as planned

When Disabled:

  • No automatic execution of scheduled launches
  • Manual execution via /execute/{launch_id} still works
  • Useful for testing, maintenance, or cost control

Request: No body required (toggle action)

Response: {status, success, message, execution_active, pending_launches}

Field Type Notes
execution_active boolean Current execution state after toggle
pending_launches integer Number of SCHEDULED launches pending execution

Status: 200 (success), 500 (server error)

Use Cases:

  • Cost management (pause automated launches)
  • Maintenance windows
  • Testing configurations without blockchain execution
  • Emergency stop for issues

GET /api/launch-config/execution/status

Get current launch execution status and pending launches count.

Request: No parameters

Response: {status, success, message, execution_active, pending_launches}

Field Type Notes
execution_active boolean Whether automatic execution is enabled
pending_launches integer Number of SCHEDULED launches in queue

Status: 200 (success), 500 (server error)

Use Cases:

  • Display toggle state in UI
  • Monitor execution status
  • Dashboard indicators
  • Pre-flight checks before scheduling

Generation Services

Router: /api/generation | Module: src/web_ui/api/generation_routes.py | Orchestrator: GenerationOrchestrator

AI-powered memecoin generation with RAG v2 workflow, session management, and progress tracking.

Generation Workflow

POST /api/generation/create - Initiate AI-powered memecoin generation with RAG retrieval

RAG v2 with CLIP similarity. 7-stage pipeline (Validation → Retrieval → Metadata → Image → Output). Estimated 8-15s completion. Session auto-cleanup after 1 hour.

Request: {prompt, selected_tags: Array<string>, generation_count: 1-5, max_examples: 1-20, session_id?: string}

Response: {success, session_id, status, message, estimated_completion_seconds}

Status: 202, 400, 500

Generation Session Tracking

Session Stages: Validation (0-20%), Retrieval (20-45%), Metadata (45-70%), Image (70-90%), Output (90-100%)

Endpoints:

  • GET /api/generation/tags - Complete tag vocabulary (19 categories, 356 tags, <50ms memory cache) | Response includes all categories: animals, technology, community, finance, entertainment, sports, food, culture, nature, gaming, art, music, education, health, politics, science, travel, fashion, miscellaneous | Status: 200
  • GET /api/generation/sessions/stats - Aggregated session statistics (30s server-side cache) | Response: {total_sessions, completed, failed, processing} | Status: 200, 500
  • GET /api/generation/status/{session_id} - Real-time progress polling | Response includes: status (queued/processing/completed/failed), progress: 0-100, current_stage, estimated_remaining_seconds, partial_results (RAG examples, sent once), generated_results (UUIDs when completed) | Status: 200, 404, 500
  • GET /api/generation/results/{session_id} - Completed results with RAG context (available after 'completed', auto-deleted after 1 hour) | Response includes: generated_tokens[], rag_context: {examples_used, similarity_scores}, total_duration_seconds | Status: 200, 404, 425, 500

Generation Error Recovery

POST /api/generation/session/{session_id}/retry

Retry a failed generation session with automatic error recovery.

Retry Conditions:

  • Session status must be failed
  • Maximum 3 retry attempts per session
  • Original request parameters are reused

Process:

  1. Validates retry eligibility (status, retry count)
  2. Resets session to pending status
  3. Increments retry counter
  4. Restarts generation using orchestrator
  5. Returns immediately (async processing)

Path Parameters:

Param Type Notes
session_id string Session identifier from original POST /create

Request: No body required

Response: {status, success, message, retry_count}

Field Type Notes
retry_count integer Number of retries for this session (1-3)
session_id string Same session ID (preserved across retries)

Status: 202 (accepted for processing), 400 (retry limit/invalid state), 404 (session not found), 500 (server error)

Error Scenarios:

  • 400: Session not in failed state
  • 400: Maximum retries exceeded (>= 3 attempts)
  • 404: Session ID not found or expired
  • 500: Orchestrator processing error

Use Cases:

  • Automatic recovery from transient failures
  • Retry after LLM API rate limits
  • Recover from temporary vector DB unavailability
  • Handle network timeouts

Best Practices:

  • Wait a few seconds before retrying (avoid immediate retry loops)
  • Monitor retry_count to avoid infinite loops
  • Check session status before retry
  • Consider exponential backoff for repeated failures

Example Flow:

// 1. Original generation fails
let status = await fetch('/api/generation/status/abc123').then(r => r.json());
// status.status === 'failed'

// 2. Wait before retry
await new Promise(resolve => setTimeout(resolve, 2000));

// 3. Retry
const retry = await fetch('/api/generation/session/abc123/retry', {
  method: 'POST'
}).then(r => r.json());
// retry.retry_count === 1

// 4. Poll for completion
// (use GET /status/{session_id} as before)

Trends Tracking

Router: /api/trends | Module: src/web_ui/api/trends_routes.py | Orchestrator: TrendOrchestrator

Real-time trend tracking with reactive Firebase watchers, in-memory caching, and prominence-based scoring.

Architecture: Reactive Firebase watchers (no polling), in-memory cache (1-20ms reads), dual collections (potential/confirmed), prominence scoring, auto-initialization on startup.

Trend Query Operations

Collections: potential, confirmed (dual-collection architecture)

hot_trends: Trends with >= 10 memecoins

Endpoints:

  • GET /api/trends/stats - Dashboard statistics from cache (~1-5ms, pure cache read, no Firebase queries) | Response: {total_trends, potential_trends, confirmed_trends, hot_trends, last_updated} | Status: 200, 500
  • GET /api/trends - List all trends with filters (collection: potential/confirmed, include_examples: 0-3, sorted by prominence score descending) | ~5-20ms without images, ~50-200ms with images | Images from res/memecoins/trends/ | Response includes: _collection, prominence_score | Status: 200, 400, 500
  • GET /api/trends/{trend_id} - Specific trend by document ID (~1-5ms cache lookup) | Response includes full trend object | Status: 200, 404, 500
  • GET /api/trends/detail/{trend_id} - ALL memecoins from trend with Base64 images (~100-500ms depending on count, slow for 50+ memecoins, cache client-side) | Images: Base64 JPG 512x512px | Response: {trend_id, trend_name, total, images_loaded, memecoins[]} | Status: 200, 404, 500

Trend Detection Control

Control automatic trend detection workflow for cost management and operational control.

POST /api/trends/detection/toggle

Toggle automatic trend detection workflow on/off.

Behavior:

  • If currently enabled → disables detection
  • If currently disabled → enables detection

When Enabled:

  • Runs full trend detection workflow
  • WebSocket → Processing → Firebase writes
  • Produces new trends from token launches
  • Incurs LLM API costs for trend analysis

When Disabled:

  • Only Firebase monitoring active (read/cache)
  • No new trend production
  • Reduces LLM API costs significantly
  • Existing trends still accessible

Request: No body required (toggle action)

Response: {status, success, message, detection_active, potential_trends, confirmed_trends}

Field Type Notes
detection_active boolean Current detection state after toggle
potential_trends integer Number of potential trends in cache
confirmed_trends integer Number of confirmed trends in cache

Status: 200 (success), 500 (server error)

Use Cases:

  • Cost management (pause expensive LLM operations)
  • Testing/debugging without production workflow
  • Maintenance windows
  • User control over expensive workflow

GET /api/trends/detection/status

Get current trend detection workflow status.

Request: No parameters

Response: {status, success, message, detection_active, potential_trends, confirmed_trends}

Field Type Notes
detection_active boolean Whether trend detection is currently active
potential_trends integer Number of potential trends (from cache)
confirmed_trends integer Number of confirmed trends (from cache)

Status: 200 (success), 500 (server error)

Use Cases:

  • Display detection toggle state in UI
  • Monitor workflow status
  • Dashboard indicators
  • Cost monitoring

Error Reference

Error Response Format

All endpoints return: {detail: string, status_code: int}

The API sanitizes errors to remove sensitive information and includes troubleshooting hints.

Common Error Patterns

Error Status Example Message
Orchestrator Not Ready 503 "Service temporarily unavailable. Orchestrator is initializing."
Validation Failed 400 "Validation failed: sol_amount must be between 0.1 and 10.0"
Resource Not Found 404 "Memecoin with token address '5xj8...' not found"
Firebase Not Initialized 503 "Firebase is not initialized. Check credentials and configuration."

Response Codes

Success: 200 (OK), 201 (Created), 202 (Accepted) Client Error: 400 (Bad Request), 404 (Not Found), 409 (Conflict), 425 (Too Early) Server Error: 500 (Internal Error), 503 (Service Unavailable)

##Additional Resources

Last Updated: January 2025 - LaunchAgencyBot Web UI v2.0 For questions or issues, see: https://github.com/Haydart/LaunchAgencyBot