morph-dex

name	morph-dex
version	1.0.0
description	DEX swap execution on Morph L2 — quote and send swaps via Bulbaswap aggregator

Morph DEX — AI Agent Skill

DEX swap operations via Bulbaswap aggregator on Morph Mainnet (Chain ID: 2818). All commands output JSON. All amounts use human-readable units.

Activation Triggers

Use this skill when the user wants to: get a swap quote, check token prices, or execute a token swap on Morph chain only. For swaps on other chains or cross-chain transfers, use the morph-bridge skill instead.

Quick Start

pip install requests eth_account

# Run from repository root
python3 scripts/morph_api.py <command> [options]

No API keys required. DEX API: https://api.bulbaswap.io

---

BGW Routing Note

Decide the mode once via the root SKILL.md and docs/social-wallet-integration.md.

• This skill handles Morph DEX quoting and local-key swap execution.
• dex-send requires --private-key (local signing only).
• Social Login Wallet users should use BGW's swap flow instead — see social-wallet-integration.md.
• dex-quote is still useful for price comparison even when BGW handles execution.

Commands

dex-quote

Get a swap quote. Returns estimated output amount and price impact. Pass --recipient to include methodParameters (calldata for on-chain execution).

# Preview quote only
python3 scripts/morph_api.py dex-quote --amount 1 --token-in ETH --token-out USDT

# With recipient (returns methodParameters.calldata for dex-send)
python3 scripts/morph_api.py dex-quote --amount 1 --token-in ETH --token-out USDT --recipient 0xYourAddr

Optional: --slippage 0.5 (default: 1%), --deadline 300 (seconds, default: 300), --protocols v2,v3.

dex-send

Sign and broadcast a swap transaction using calldata from dex-quote --recipient. Uses methodParameters fields (to, value, calldata) from the quote response.

python3 scripts/morph_api.py dex-send --to 0xRouterAddr --value 0.001 --data 0xCalldata... --private-key 0xKey

dex-approve

Approve an ERC-20 token for spending by a DEX router. Required before swapping ERC-20 tokens.

python3 scripts/morph_api.py dex-approve --token USDT --spender 0xRouterAddr --amount 1000 --private-key 0xKey

dex-allowance

Check the ERC-20 allowance granted to a spender.

python3 scripts/morph_api.py dex-allowance --token USDT --owner 0xOwnerAddr --spender 0xRouterAddr

---

Safety Rules

1. Always confirm with the user before executing dex-send or dex-approve — show the swap details (token pair, amount, slippage, router address) before signing.
2. Private keys are used locally for signing only — never sent to any API.
3. DEX quotes expire quickly — get a fresh quote and send immediately.

Critical Notes

• Morph chain only — dex-quote and dex-send only work for tokens on Morph. For other chains, use bridge commands.
• DEX quotes expire quickly — get a fresh quote and send immediately.
• Always use --slippage to protect against price movement.
• dex-quote returns amounts in human-readable units.
• dex-send requires methodParameters from a quote with --recipient.

Common Workflows

Swap tokens (full flow with approval):

dex-allowance (check if approved) → dex-approve (if needed) → dex-quote --recipient 0xAddr → dex-send

Swap tokens:

dex-quote --recipient 0xAddr (get calldata) → dex-send (sign & broadcast)

Swap with alt-fee gas payment:

dex-quote --recipient 0xAddr → altfee-send (morph-altfee skill, pay gas with alt token)

Cross-Skill Integration

• Use token-search (morph-explorer) to find token contract addresses before quoting.
• Use balance / token-balance (morph-wallet) to verify funds before swapping.
• Use altfee-send (morph-altfee) instead of dex-send to pay gas with alternative tokens.
• Use dex-quote --recipient 0xEOA calldata inside 7702-batch (morph-7702) for atomic approve + swap in a single transaction.