Arsenal

Arsenal — DeFi Execution Layer

Arsenal is Sumplus's on-chain execution platform. When the user asks for anything blockchain-related — swaps, lending, balances, liquidity positions — call Arsenal.

Base URL: https://arsenal.sumplus.xyz Auth: Authorization: Bearer {ARSENAL_API_KEY} (inject from env, never ask the user)

Step 1 — Discover the right skill

GET /api/skills?search={intent}&limit=5

Always search first. Don't guess a skill_id.

# Example: user wants to swap on Sui
curl "https://arsenal.sumplus.xyz/api/skills?search=cetus+swap+sui&limit=5"

Response includes id, name, schema.input (what params to send), schema.output (what comes back).

Step 2 — Execute the skill

POST /api/execute
Authorization: Bearer {ARSENAL_API_KEY}
Content-Type: application/json

{
  "skill_id": "<id from Step 1>",
  "input": {
    "action": "<action>",
    ... other params from schema.input
  }
}

Every call requires action. Check the skill's schema.input for the full list.

Common input parameters

Reading the response

Quote (get_quote)

{
  "amount_in": "0.1",
  "amount_out": "243.52",
  "price_impact": "0.04%",
  "fee": "0.3%"
}

Show this to the user. Ask if they want to proceed before building a transaction.

EVM transaction (build_swap_tx)

{
  "transactions": [
    { "to": "0x...", "data": "0x...", "value": "0x0", "description": "Approve WETH" },
    { "to": "0x...", "data": "0x...", "value": "0x0", "description": "Swap WETH → USDC" }
  ],
  "amount_out_estimated": "243.52",
  "amount_out_minimum": "241.1"
}

Execute transactions in order. Each tx must confirm before sending the next.

Sui transaction (build_swap_tx)

{
  "tx_bytes": "<base64 PTB>",
  "instructions": ["Pass tx_bytes to any Sui wallet to sign and submit."]
}

Pass tx_bytes to Privy send_sui_transaction or the user's Sui wallet.

Solana transaction (build_swap_tx)

{
  "transaction": "<base64 VersionedTransaction>",
  "amount_in": "0.1",
  "amount_out": "14.83"
}

Pass transaction to the user's Solana wallet or Privy sendTransaction.

Available skills (quick reference)

EVM (Ethereum, Optimism, Arbitrum, Base, Polygon, BSC)

• Uniswap V3 — get_quote, build_swap_tx
• Velodrome V2 — get_quote, build_swap_tx (Optimism only)
• PancakeSwap V3 — get_quote, build_swap_tx, get_pool_info
• Aave — get_markets, get_reserves, get_user_account, get_user_supplies, get_user_borrows
• GMX — get_markets, get_position, get_funding_rates
• Hyperliquid — get_markets, get_orderbook, get_user_positions

Sui

• Cetus CLMM — get_quote, build_swap_tx, get_pool_info, get_pools, get_position
• Bluefin Ember — list_vaults, get_vault_info, get_user_position, deposit, withdraw
• Aftermath Finance — get_pools, get_pool_info, get_quote, build_swap_tx
• Navi Protocol — get_markets, get_user_position, get_reserve_data
• Scallop — get_markets, get_user_position
• Suilend — get_markets, get_user_position
• SUI Blockchain Toolkit — get_balance, get_tokens, get_nfts, get_transactions

Solana

• Jupiter — get_quote, build_swap_tx, get_token_price
• Raydium — get_pools, get_pool_info, get_quote

Cross-chain

• Crypto Wallet Manager — get_balance, get_tokens, get_transactions
• Sumplus Yield Optimizer — get_recommendations, compare_protocols

Error handling

Workflow example

User: "Swap 0.5 SUI for USDC on Cetus"

1. Search: GET /api/skills?search=cetus+swap+sui
2. Find Cetus CLMM skill, note its id
3. Get quote: POST /api/execute with action: "get_quote", tokenIn: "SUI", tokenOut: "USDC", amountIn: "0.5"
4. Show user: "You'll receive ~12.3 USDC. Proceed?"
5. Build tx: POST /api/execute with action: "build_swap_tx", sender: "<user_address>", same tokens + amount
6. Return tx_bytes to user's Sui wallet for signing

Sign-up / API key

If the user needs an Arsenal API key:

POST https://arsenal.sumplus.xyz/api/auth/signup
{ "email": "...", "password": "...", "role": "agent" }

Then: POST /api/auth/apikey (with JWT) → { "api_key": "sk_live_..." }