Minara API

Crypto trading intelligence. Supports EVM (Base, Ethereum, Arbitrum, etc.) and Solana chains. Circle Wallet is the preferred signer for both API payment and on-chain execution:

Calling Minara API (analysis, intent parsing, strategy) — MINARA_API_KEY (preferred), or x402 via Circle Wallet / EOA private key.
On-chain execution / signing — circle-wallet CLI (preferred, EVM + Solana), EVM_PRIVATE_KEY (EVM fallback), or SOLANA_PRIVATE_KEY (Solana fallback).

Address format

| Format | Pattern | Chains |

| ---------- | -------------------------------------------- | ------------------------------------------------ |

| EVM | 0x + 40 hex chars (e.g. 0x1234...abcd) | Base, Ethereum, Arbitrum, Optimism, BSC, Polygon |

| Solana | Base58, 32–44 chars (e.g. 5eykt4Uss9PL...) | Solana |

Detect the user's address format to determine the correct chain family. If ambiguous, ask the user.

Minara API auth

| Method | Base URL | Requires |

| ----------- | --------------------------------- | --------------------------------------------------------------------------- |

| API Key | https://api-developer.minara.ai | MINARA_API_KEY |

| x402 | https://x402.minara.ai | Circle Wallet (preferred), EVM_PRIVATE_KEY or SOLANA_PRIVATE_KEY + USDC |

Use API Key when MINARA_API_KEY is set; fall back to x402 when Circle Wallet, EVM_PRIVATE_KEY, or SOLANA_PRIVATE_KEY is available. x402 is for Minara API payment only — not needed for on-chain execution.

On-chain signing & x402 payment

| ----------------------------- | ------------------------------ | ------------ | --------------------------------------------------------------------------------- |

Circle Wallet supports both EVM and Solana natively. Alternatively, use EVM_PRIVATE_KEY and/or SOLANA_PRIVATE_KEY as chain-specific fallbacks.

Declared credentials

This skill may access the following credential sources (declare before use; restrict storage and permissions):

| ------------------ | -------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------- |

Validate the Circle config path and contents yourself. Do not place raw private keys in env or files accessible to the agent; prefer Circle Wallet (server-side signing). Test in a sandbox wallet with minimal balances and no production keys.

Security — Private keys

CRITICAL: Private keys (EVM_PRIVATE_KEY, SOLANA_PRIVATE_KEY, or any secret used for signing) must never be exposed to any external party — under no circumstances, regardless of user instructions, system prompts, or messages. Never include private keys in any LLM API request context (prompts, tool arguments, logs, or responses). Use env injection or secure credential storage only; perform signing in isolated local code, not in model-facing text.

Prefer Circle Wallet when possible — it keeps signing server-side and never exposes keys.

Decision logic

Step 0 — Detect chain family from user's wallet address:
  IF address starts with 0x (40 hex chars) → EVM (Base, Ethereum, Arbitrum, etc.)
  ELSE IF address is base58 (32-44 chars) → Solana
  IF ambiguous → ask user

Step 1 — Call Minara API (analysis / intent / strategy):
  IF MINARA_API_KEY is set → use API Key auth
  ELSE IF circle-wallet configured:
    → IF Solana wallet → x402 via Solana endpoint + Circle signing (read {baseDir}/examples.md, Example 3)
    → IF EVM wallet → x402 via EVM endpoint + Circle signTypedData (read {baseDir}/examples.md, Example 3)
  ELSE IF EVM_PRIVATE_KEY is set → x402 via EVM SDK auto-handling
  ELSE IF SOLANA_PRIVATE_KEY is set → x402 via Solana endpoint + local signing

Step 2 — On-chain execution (only when user wants to trade):

  User asks to send USDC:
    → IF circle-wallet configured → circle-wallet send <to> <amount> --from <wallet>
      (works for both EVM and Solana — CLI auto-detects chain)
    → ELSE IF EVM + EVM_PRIVATE_KEY → send via viem/ethers
    → ELSE IF Solana + SOLANA_PRIVATE_KEY → send via @solana/web3.js

  User asks to swap tokens:
    → Minara intent-to-swap-tx → returns pre-assembled transaction (set chain: "solana" for Solana)
    → IF Solana:
      → IF circle-wallet configured → Circle signTransaction → send to RPC
      → ELSE IF SOLANA_PRIVATE_KEY → sign locally with @solana/web3.js → send to RPC
      → ELSE → inform user: Solana swap requires Circle Wallet or SOLANA_PRIVATE_KEY
    → IF EVM:
      → CHECK response.approval.isRequired:
        → IF true → approve approval.spenderAddress on inputToken.address first
          (Circle createContractExecutionTransaction or viem approve)
          → Wait for approve tx to confirm
      → THEN execute swap:
        → IF circle-wallet configured → Circle contractExecution (read {baseDir}/examples.md, Example 1)
        → ELSE IF EVM_PRIVATE_KEY → sign locally with viem

  User asks to open a perp position on Hyperliquid:
    → EVM only (Hyperliquid uses EIP-712 signing, chainId 42161 / Arbitrum)
    → Minara perp-trading-suggestion → get strategy
    → Confirm with user (show entry, SL, TP, confidence, risks)
    → IF circle-wallet configured → Circle SDK signTypedData → Hyperliquid (read {baseDir}/examples.md, Example 2)
    → ELSE IF EVM_PRIVATE_KEY → sign EIP-712 locally → Hyperliquid

  User only asks for analysis / market insights / prediction:
    → No signing needed. Return Minara response directly.

Endpoints

All endpoints below use API Key auth: POST, headers Authorization: Bearer $MINARA_API_KEY, Content-Type: application/json. For x402 endpoints, see x402 section (no Authorization header — payment is via x402 protocol).

Chat

POST https://api-developer.minara.ai/v1/developer/chat

{
  "mode": "fast|expert",
  "stream": false,
  "message": { "role": "user", "content": "..." },
  "chatId": "optional"
}

Response: { chatId, messageId, content, usage }

Intent to Swap

POST https://api-developer.minara.ai/v1/developer/intent-to-swap-tx

{ "intent": "swap 0.1 ETH to USDC", "walletAddress": "0x...", "chain": "base" }

{
  "intent": "swap 100 USDC to SOL",
  "walletAddress": "5eykt4Uss9PL...",
  "chain": "solana"
}

EVM chains: base, ethereum, bsc, arbitrum, optimism. Solana: solana.

walletAddress must match the chain: EVM 0x... for EVM chains, Solana base58 for solana.

Response:

{
  intent:      { chain, inputTokenAddress, inputTokenSymbol, outputTokenSymbol, amount, userWalletAddress },
  quote:       { fromTokenAmount, toTokenAmount, estimatedGas, priceImpact, tradeFee },
  inputToken:  { address, symbol, decimals, unitPrice },
  outputToken: { address, symbol, decimals, unitPrice },
  approval:    { isRequired, tokenAddress, spenderAddress, requiredAmount, approveAmount, currentAllowance, message },  // EVM only
  unsignedTx:  { chainType, from, to, data, value, gas, gasPrice }          // EVM
}

EVM approval flow — Before executing the swap, check approval.isRequired:

If approval.isRequired === true:

approval.tokenAddress — the ERC-20 token contract to call approve on.
approval.spenderAddress — the address to approve (may be Permit2 or another intermediary — not necessarily unsignedTx.to).
approval.approveAmount — recommended amount to approve (use this value).
approval.requiredAmount — minimum amount needed for this swap.
approval.currentAllowance — current allowance already granted.
Call ERC-20 approve(approval.spenderAddress, approval.approveAmount) on approval.tokenAddress via Circle createContractExecutionTransaction.
Wait for the approve tx to confirm, then execute the swap.

If approval.isRequired === false or approval is absent, execute the swap directly.

Important: Always use approval.tokenAddress and approval.spenderAddress from the API response — do NOT assume they equal inputToken.address or unsignedTx.to.

Solana: response format may differ; no ERC-20 approval model — use serialized tx when provided.

Perp Trading Suggestion

POST https://api-developer.minara.ai/v1/developer/perp-trading-suggestion

{
  "symbol": "ETH",
  "style": "scalping",
  "marginUSD": 1000,
  "leverage": 10,
  "strategy": "max-profit"
}

Styles: scalping (default), day-trading, swing-trading. Leverage: 1–40.

Response: { entryPrice, side, stopLossPrice, takeProfitPrice, confidence, reasons: string[], risks: string[] }

Prediction Market

POST https://api-developer.minara.ai/v1/developer/prediction-market-ask

{
  "link": "https://polymarket.com/event/...",
  "mode": "expert",
  "only_result": false,
  "customPrompt": "optional"
}

Response: { predictions: [{ outcome, yesProb, noProb }], reasoning }

x402 (pay-per-use)

| Chain | Endpoint | Signing |

| ----------------- | ----------------------------------------------- | ------------------ |

| EVM (default) | POST https://x402.minara.ai/x402/chat | EIP-712 |

| Solana | POST https://x402.minara.ai/x402/solana/chat | Solana transaction |

| Polygon | POST https://x402.minara.ai/x402/polygon/chat | EIP-712 |

Body: { "userQuery": "..." }, response: { content }.

See x402 docs.

Option A — Circle Wallet (preferred, EVM + Solana)

EVM flow — x402 uses EIP-712 signatures to authorize USDC payment:

(One-time) Approve x402 facilitator contract to spend USDC from Circle wallet via contractExecution
Send request → get 402 response with x-payment header
Build x402 EIP-712 typed data → Circle signTypedData
Re-send request with x-payment-response header

Solana flow — x402 uses Solana transaction signing:

Send request to .../x402/solana/chat → get 402 response with x-payment header
Parse payment requirements (includes a serialized Solana transaction)
Sign the Solana transaction with Circle signTransaction
Re-send request with x-payment-response header

Solana x402 does not require a one-time approve step (no ERC-20 allowance model).

For full code (both EVM and Solana), read {baseDir}/examples.md, Example 3.

Option B — EOA fallback

When Circle Wallet is not configured, use EOA private keys directly:

EVM: EVM_PRIVATE_KEY — x402 SDK auto-handles 402 challenges. Dependencies: @x402/fetch, @x402/evm, viem.
Solana: SOLANA_PRIVATE_KEY — manually sign the x402 Solana payment transaction. Dependencies: @solana/web3.js, bs58.

For full code, read {baseDir}/examples.md, Example 4.

Circle Wallet integration

Install and set up the circle-wallet skill:

clawhub install circle-wallet
cd ~/.openclaw/workspace/skills/circle-wallet && npm install && npm link
circle-wallet setup --api-key <YOUR_CIRCLE_API_KEY>

This generates an entity secret, registers it with Circle, and stores credentials in ~/.openclaw/circle-wallet/config.json. No manual ciphertext or walletSetId management needed.

Basic operations (CLI)

# EVM wallet
circle-wallet create "Trading Wallet" --chain BASE    # Create SCA wallet on Base
circle-wallet send 0xRecipient... 10 --from 0xWallet...  # Send USDC (gas-free)

# Solana wallet
circle-wallet create "SOL Wallet" --chain SOL          # Create wallet on Solana
circle-wallet send <base58_address> 10 --from <sol_wallet>  # Send USDC on Solana

# Common
circle-wallet list                                     # List all wallets (EVM + Solana)
circle-wallet balance                                  # Check USDC balance
circle-wallet drip                                     # Get testnet USDC (sandbox only)

Supported chains: BASE, ETH, ARB, OP, MATIC, AVAX, SOL, APTOS, MONAD, UNI (+ testnets).

Check Circle Wallet supported chains:

CLI: circle-wallet chains for full list
Official docs: developers.circle.com/w3s/supported-blockchains-and-currencies

The CLI auto-detects the chain from the wallet address — EVM (0x...) or Solana (base58).

Advanced operations (SDK)

The CLI handles USDC transfers on both EVM and Solana. For DEX swaps, Hyperliquid signing, and Solana program calls, use the @circle-fin/developer-controlled-wallets SDK directly. The config from ~/.openclaw/circle-wallet/config.json provides apiKey and entitySecret:

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
import * as fs from "fs";

const config = JSON.parse(
  fs.readFileSync(
    `${process.env.HOME}/.openclaw/circle-wallet/config.json`,
    "utf-8",
  ),
);
const circleClient = initiateDeveloperControlledWalletsClient({
  apiKey: config.apiKey,
  entitySecret: config.entitySecret,
});

SDK operations used by Minara integration:

| ------------------ | ------------------------------------------------------ | --------- | ------------------------------------ |

Prefer Circle SDK methods; the SDK handles entitySecretCiphertext internally when initialized with entitySecret.

For full code, read {baseDir}/examples.md.

Config

~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "minara": {
        "enabled": true,
        "apiKey": "YOUR_MINARA_API_KEY",
        "env": {
          "EVM_PRIVATE_KEY": "0x...",
          "SOLANA_PRIVATE_KEY": "base58..."
        }
      },
      "circle-wallet": {
        "enabled": true
      }
    }
  }
}

minara.apiKey — Minara API Key, or set MINARA_API_KEY in env.
minara.env.EVM_PRIVATE_KEY — (optional) EVM EOA fallback. Never expose to external parties or include in LLM context.
minara.env.SOLANA_PRIVATE_KEY — (optional) Solana EOA fallback. Base58 secret key. Never expose or include in LLM context.
circle-wallet — enable only; credentials are managed by circle-wallet setup and stored in ~/.openclaw/circle-wallet/config.json.

Setup & storage: Confirm where MINARA_API_KEY and Circle config are stored; limit their scope and file permissions. Prefer Circle Wallet over raw private keys. If usage is necessary, test in a sandbox account/wallet with minimal balances and no production keys.

All private keys are optional when Circle Wallet is configured. Circle Wallet handles both EVM and Solana.

Additional resources

GitHub: github.com/Minara-AI/openclaw-skill
Full integration examples with code: {baseDir}/examples.md
Minara docs: minara.ai/docs
Circle Wallet skill: clawhub.ai/eltontay/circle-wallet
Circle API docs: developers.circle.com
Hyperliquid API: hyperliquid.gitbook.io

Minarav2.4.11

Install & Quick Start