feat(binance): integrate Binance Spot Trading plugin into Vibekit registry

[HillaryMaende]

Summary

Related Issue(s):

• Binance Spot Trading Plugin integration ([New Protocol Integration]: Binance Spot Trading Plugin #251)

Provide a brief description of what this PR accomplishes:

This PR integrates the Binance Spot Trading Plugin into the Vibekit onchain-actions plugins registry and syncs the fork with upstream main. It enables agents to execute spot trades on Binance, retrieve market data, and manage account information via MCP-compatible tools.

Type of Change:

• ✨ New feature (adds functionality)
• 🔌 Protocol integration (adds support for new DeFi protocol)

🧪 Testing

Tests Performed:

• Local install and manual verification of plugin README and registry integration

Steps to Run Tests:

• pnpm install
• pnpm -r build
• pnpm -r test

Checklists

Code Quality

• Code follows project conventions and style guidelines
• TypeScript compilation passes (pnpm build)
• Linting passes (pnpm lint:check)
• All tests pass (pnpm test)
• No any types introduced
• Error handling implemented appropriately
• Security best practices followed (no exposed secrets/keys)

Documentation

• Code is self-documenting or includes necessary comments
• README updated
• API/interface changes documented

Deployment Notes

Deployment Considerations:

• Requires Binance API credentials for functionality

New or Changed Environment Variables:

• BINANCE_API_KEY
• BINANCE_API_SECRET
• BINANCE_USE_TESTNET (optional)
• BINANCE_API_BASE_URL (optional)

Breaking Changes or Migration Steps:

• None

New Dependencies Added:

• None outside the plugin scope

Additional Context

🏷️ Protocol Name
Binance

🔧 Protocol Type
Swapping/DEX

📝 Protocol Description
The Binance Spot Trading Plugin integrates Binance’s Spot Trading API into the Arbitrum Vibekit framework, enabling on-chain agents to perform real-time cryptocurrency swaps through Binance’s centralized exchange infrastructure.

Key features include:

• Spot Trading: Execute market buy/sell orders across all Binance trading pairs.
• Real-Time Market Data: Fetch live prices, order books, and token metadata.
• Account Management: Retrieve balances, permissions, and account status.
• Error & Rate Limit Handling: Built-in retry logic with exponential backoff for network and API rate limits.
• Secure Configuration: Environment-based API key management with testnet support and optional market-maker subdomain usage.

This plugin bridges Arbitrum-based agent frameworks with Binance liquidity, enabling hybrid DeFi–CeFi trading and automated strategy execution.

📚 Protocol Documentation
https://developers.binance.com/docs/binance-spot-api-docs/rest-api/general-api-information

🌐 Supported Networks
All Binance Exchange supported Networks

🎯 Capabilities
The Binance Spot Trading Plugin supports the following operations:

• Single Token Swaps: Execute direct market buy/sell orders between any two supported Binance spot pairs.
• Real-Time Pricing: Fetch live market prices and order book depth for accurate trade execution.
• Slippage Handling: Trades execute at current market prices, with optional client-side slippage tolerance logic.
• Price Impact Awareness: Uses live order book data to estimate effective execution price and potential price impact.
• Token Discovery: Automatically loads all available Binance spot pairs for supported base and quote assets.

📎 Additional Information

🔒 Security Considerations:

• API keys must be stored securely (environment variables or secret manager).
• Recommended: enable IP restrictions and 2FA on Binance accounts.
• Use Binance Testnet for initial testing and validation before deploying to mainnet.
• API keys should only have Spot Trading permissions (no withdrawal access).

⚙️ Special Requirements:

• Requires valid Binance API credentials.
• Network access to Binance REST endpoints is needed.
• Supports both mainnet and testnet environments through configuration.

📈 Integration Notes:

• Automatically registers with the Vibekit registry when environment variables are set.
• Built-in rate limit and retry handling compliant with Binance API constraints.
• Health check endpoints for trading permissions, balance retrieval, and market data.

Implementation Required

Plugin Registration & Configuration

• Ensure the MCP Server loads and registers the Binance Spot Plugin automatically when env vars are detected (BINANCE_API_KEY, BINANCE_API_SECRET, etc.).
• Add support for manual plugin registration through the MCP configuration interface.

Swap Execution Handler

• Implement a swap action handler within MCP mapping generic Vibekit swap intents (e.g., SwapAction) to Binance spot market orders (buy/sell).
• Support order submission, confirmation, and response parsing from Binance’s REST API.

Market Data Adapter

• Add a price feed adapter to fetch real-time market data, including current prices, order books, and symbol metadata (precision, minQty).
• Enable MCP to query these endpoints for accurate price estimation and slippage calculations.

Account Interface

• Implement endpoints to retrieve balances, trading permissions, and account status from Binance.
• Map responses into MCP’s standardized balance/account schema.

Error & Rate Limit Handling

• Integrate the plugin’s exponential backoff and retry logic into MCP’s global task runner or job queue.
• Log and surface Binance-specific error codes for visibility.

Environment & Secrets Management

• Configure secure storage and access for Binance API credentials.
• Ensure secrets are injected safely into the MCP runtime without being logged or exposed.