Crypto Buy/Sell ExecModule - Quick Reference

Overview

The Crypto Buy/Sell ExecModule (payment.crypto.buy_sell) enables workflows to execute cryptocurrency transactions across multiple platforms including Coinbase, Kraken, and Binance.

Supported Platforms

Platform	Endpoint	Order Types	Features
Coinbase	REST v1 API	Market, Limit	Full order lifecycle, sandbox support
Kraken	REST v0 API	Market, Limit	Advanced order types, volume controls
Binance	REST v3 API	Market, Limit	High liquidity, testnet available
Sandbox	Coinbase Sandbox	Market, Limit	Testing & development

Configuration

Basic Setup

{
  "exchange_platform": "coinbase",
  "action": "buy",
  "cryptocurrency": "BTC",
  "fiat_currency": "USD",
  "amount": 0.5,
  "order_type": "market",
  "integration_account_id": "{{integrationAccountId}}"
}

Complete Configuration with Advanced Options

{
  "integration_account_id": "uuid-from-integration-account",
  "exchange_platform": "coinbase",
  "action": "buy",
  "cryptocurrency": "BTC",
  "fiat_currency": "USD",
  "amount": 0.5,
  "order_type": "limit",
  "price_limit_usd": 45000,
  "time_in_force": "immediate",
  "auto_convert": false,
  "metadata": {
    "agent_id": "{{agentId}}",
    "workflow_id": "{{workflowId}}",
    "initiated_by": "agent"
  },
  "idempotency_key": "crypto_{{requestId}}",
  "webhook_url": "https://webhook.example.com/crypto/callback",
  "notifications": {
    "on_fill": true,
    "on_partial_fill": false,
    "on_cancel": true
  },
  "risk_controls": {
    "velocity_check": true,
    "max_daily_volume_usd": 100000,
    "max_single_order_usd": 25000
  }
}

Field Reference

Core Fields

Field	Type	Required	Description
integration_account_id	UUID	Yes	Reference to IntegrationAccount with API credentials
exchange_platform	String	Yes	Platform: coinbase, coinbase-sandbox, kraken, binance
action	String	Yes	Order action: buy or sell
cryptocurrency	String	Yes	Crypto code: BTC, ETH, USDC, etc.
fiat_currency	String	Yes	Fiat code: USD, EUR, GBP, etc.
amount	Number	Yes	Amount of cryptocurrency to buy/sell
order_type	String	Yes	market (immediate) or limit (price-based)

Advanced Options

Field	Type	Default	Description
price_limit_usd	Number	null	For limit orders, max/min price per unit
time_in_force	String	immediate	immediate, post_only, or fill_or_kill
auto_convert	Boolean	false	Auto-convert stablecoins
idempotency_key	String	auto-generated	Unique key for idempotent requests
webhook_url	String	null	Callback URL for order updates

Risk Controls

{
  "risk_controls": {
    "velocity_check": true,
    "max_daily_volume_usd": 100000,
    "max_single_order_usd": 25000
  }
}

Fails order if:

• Single order > max_single_order_usd
• Daily total > max_daily_volume_usd

Output (WorkflowState)

Order results stored in crypto.order.result:

{
  "status": "success",
  "order_id": "order-uuid",
  "order_status": "filled",
  "exchange_platform": "coinbase",
  "action": "buy",
  "cryptocurrency": "BTC",
  "fiat_currency": "USD",
  "amount_requested": 0.5,
  "filled_amount": 0.5,
  "filled_price": 45000.5,
  "total_value": 22500.25,
  "timestamp": "2025-10-19T15:30:45Z"
}

IntegrationAccount Setup

For Coinbase

1. Create API Key in Coinbase:

   • Dashboard → Settings → API → Create a New Key
   • Permissions: wallet:accounts:read, wallet:transactions:create
   • Restrict to your IP (recommended)

2. Create IntegrationAccount:

   • API Key: Paste your Coinbase API Key
   • Password: Paste your Coinbase API Secret
   • Account Type: production or sandbox

For Kraken

1. Create API Key in Kraken:

   • Settings → API → Generate New Key
   • Permissions: Query Trades, Query Open Orders and Trades, Create & Modify Orders, Cancel Orders

2. Create IntegrationAccount:

   • API Key: Paste your Kraken Public Key
   • Password: Paste your Kraken Private Key

For Binance

1. Create API Key in Binance:

   • Account → API Management → Create API Key
   • Spot Trading: Enable
   • IP Whitelist: Recommended

2. Create IntegrationAccount:

   • API Key: Paste your Binance API Key
   • Password: Paste your Binance Secret Key

Example Workflows

Simple Market Buy

Task: Buy 0.5 BTC at market rate
  Module: Crypto Buy/Sell
    integration_account_id: "{{coinbaseAccount}}"
    exchange_platform: "coinbase"
    action: "buy"
    cryptocurrency: "BTC"
    fiat_currency: "USD"
    amount: 0.5
    order_type: "market"

Risk-Controlled Limit Order

Task: Buy BTC with limits and notifications
  Module: Crypto Buy/Sell
    exchange_platform: "coinbase"
    action: "buy"
    amount: 1.0
    order_type: "limit"
    price_limit_usd: 43500
    notifications:
      on_fill: true
      on_partial_fill: true
    risk_controls:
      max_single_order_usd: 50000
      max_daily_volume_usd: 200000

Multi-Exchange with Failover

Task: Attempt buy on Coinbase, failover to Kraken
  Modules:
    - Crypto Buy/Sell (Coinbase)
    - Branch Module (check error status)
    - Crypto Buy/Sell (Kraken) [if error]

Error Handling

Common Errors

Error	Cause	Solution
Integration account not found	Invalid integration_account_id	Verify account UUID in IntegrationAccount
Order value exceeds maximum	Violates risk controls	Reduce amount or increase limits
Invalid cryptocurrency	Unsupported crypto on exchange	Check exchange for supported pairs
Insufficient balance	Account has insufficient funds	Add funds to account
Invalid API credentials	API key or secret wrong	Re-authenticate in IntegrationAccount

Error Output (WorkflowState)

Errors stored in crypto.order.error:

{
  "status": "error",
  "error": "Order value 50000.00 exceeds maximum 25000.00",
  "timestamp": "2025-10-19T15:30:45Z"
}

Security Considerations

1. API Keys: Store in IntegrationAccount with @SecureField encryption
2. Idempotency: Always use idempotency_key to prevent duplicate orders
3. IP Whitelisting: Enable on exchange for additional security
4. Webhook URLs: Must use HTTPS for callbacks
5. Volume Limits: Set conservative max_daily_volume_usd to limit exposure

Supported Cryptocurrencies

Code	Name	Exchanges
BTC	Bitcoin	Coinbase, Kraken, Binance
ETH	Ethereum	Coinbase, Kraken, Binance
USDC	USD Coin	Coinbase, Kraken, Binance
USDT	Tether	Kraken, Binance
SOL	Solana	Kraken, Binance
ADA	Cardano	Kraken, Binance

Check exchange for complete list

Best Practices

1. Test First: Start with coinbase-sandbox before production
2. Idempotency: Every workflow run should use unique idempotency_key
3. Monitoring: Enable all notifications for production orders
4. Risk Limits: Set conservative daily/per-order limits
5. Logging: Check WorkflowState crypto.order.result for audit trail

Frontend Integration

Form Field Example

{
  fieldType: "select",
  name: "exchange_platform",
  label: "Exchange Platform",
  required: true,
  options: [
    { value: "coinbase", label: "Coinbase" },
    { value: "coinbase-sandbox", label: "Coinbase Sandbox" },
    { value: "kraken", label: "Kraken" },
    { value: "binance", label: "Binance" }
  ],
  helperText: "Select the cryptocurrency exchange to execute the order"
}

Related Modules

• Payment → MasterCard AgentPay: Credit card payments
• API → REST Generic: Custom API integrations
• Data → Map/Filter: Transform and filter crypto data
• Branching → If/Then: Conditional crypto logic