Badwhale API Skill

BadWhale API Skill

This skill exposes two capabilities:

Authorized use only. BadWhale is a commercial security service for testing whether a system you own or are explicitly authorized to assess correctly detects forged ("fake") deposits. Do not use it against third-party systems without written authorization. The operator is responsible for ensuring every target address belongs to an in-scope, authorized test.

Language: instructions below are in English; respond to the user in the language they wrote in (the user-facing templates can be translated accordingly).

Script invocation

The agent calls the BadWhale API only through skill/scripts/bw.py, which reads credentials from the environment variables BADWHALE_BASE_URL and BADWHALE_API_KEY.

Script location. skill/scripts/bw.py lives inside this skill's own directory (the directory that contains this SKILL.md), not the current working directory. Resolve the path against the skill directory; if the agent's working directory is elsewhere, the bare relative path will not be found.

Credentials — important. Each command runs in a fresh shell, so a separate export in an earlier step does not persist. Always pass credentials inline on the same command line, e.g.:

BADWHALE_BASE_URL="$BADWHALE_BASE_URL" BADWHALE_API_KEY="$BADWHALE_API_KEY" python skill/scripts/bw.py chains

If the variables are already exported in the user's shell profile, the inline prefix is harmless (it just re-passes the same values). If you only have the raw values, substitute them directly. If neither is available, ask the user for the API URL and key before running anything. Exit code 10 means the script saw no credentials — fix the invocation, do not retry the bare form.

For brevity the commands below are written as python skill/scripts/bw.py …, but every invocation must carry the credential prefix shown above.

bw.py exit codes:

Execution flow (7 steps)

Step 1: Connectivity + credential check

BADWHALE_BASE_URL="$BADWHALE_BASE_URL" BADWHALE_API_KEY="$BADWHALE_API_KEY" python skill/scripts/bw.py health

• Exit code 10: missing BADWHALE_BASE_URL or BADWHALE_API_KEY — set the env vars first, then continue.
• Exit code 1 / 3: treat as a connection or API-service issue — do not proceed to submit or poll this time.
• Exit code 0: continue.

Step 2: Discover available chains and networks (on first run)

python skill/scripts/bw.py chains

Step 3: Parameter check

Users often say "testnet", "测试网", "test chain" and similar generic words, but the server's actual network names differ. Never submit the literal string "testnet" as a network.

Handling rules:

1. The user said an alias like "testnet" / "测试网" / "test":
   • The chain has exactly one non-mainnet network → tell the user the real name and confirm: "The testnet for {chain} is {real_name}, use this? (yes/no)"
   • Multiple non-mainnet networks → list them and let the user choose.
   • Only mainnet → tell the user this chain has no testnet, and ask whether to switch to mainnet.
2. The user gave a network name that actually exists in /chains (e.g. sepolia / nile) → use it directly.

Step 4: Final confirmation before submit

Before POST /batches, you must show the final request and require an explicit yes:

About to submit the following test, please confirm:

• Chain: ethereum / mainnet
• Token: ETH
• Target: 0x7d7f...64bb
• Amount: 0.1 (if using the default, state it comes from the system defaultAmount in GET /chains)
• Memo: customer-001 (omit this line if the user provided no memo)

Note: tests for XRP / DOT / FIL may show a small-amount deposit as successful. As long as it is not a large-amount success, this is generally not abnormal; focus on whether the receiver mistakenly treats a large deposit as successful. (XRP/DOT/FIL only)

Proceed? (yes / no)

Step 5: Submit the batch

Assemble the request body JSON and pipe it to bw.py submit via stdin:

JSON body format:

{
  "clientRequestId": "skill-<unix_ts>-<rand4>",
  "transactions": [
    {
      "chain": "<chain>",
      "network": "<network>",
      "token": "<token>",
      "to": "<target>"
    }
  ]
}

Field rules:

• transactions holds 1 entry by default; add more only when the user explicitly asks for multiple.
• chain / network / token / to must come from user input and be validated against /chains.
• Optional fields: amount, memo.
• amount: pass only if the user provided it; otherwise omit it from the JSON so the server uses the token's defaultAmount.
• memo: pass only if the user explicitly provided it; otherwise omit.
• clientRequestId: generate skill-<unix_ts>-<rand4>; on IDEMPOTENCY_CONFLICT, change it and retry once.
• callbackUrl: do not pass it in the conversational submit flow, to avoid introducing webhook behavior.

Example command:

echo '{
  "clientRequestId": "skill-1715500800-a3f2",
  "transactions": [
    {
      "chain": "ethereum",
      "network": "mainnet",
      "token": "ETH",
      "to": "0x0000000000000000000000000000000000000001",
      "amount": "0.01"
    }
  ]
}' | BADWHALE_BASE_URL="$BADWHALE_BASE_URL" BADWHALE_API_KEY="$BADWHALE_API_KEY" python skill/scripts/bw.py submit

Step 6: Poll status

python skill/scripts/bw.py poll <batchId>

• Poll every 3 seconds, for at most 5 minutes. On timeout, stop and ask the user whether to keep polling.
• Only print a one-line progress update when the batch or task status changes (progress: queued → pending → running …). If nothing changed, stay silent — do not spam.

Step 7: Render the result

Success (batch.status = completed)

✅ Test completed

🔷 ethereum mainnet token: ETH　target: 0x7d7f...64bb　amount: 0.1 Tx: https://etherscan.io/tx/0x9f86d0... Tx: https://etherscan.io/tx/0xabc123... Tx: https://etherscan.io/tx/0xdef456...

Partial (batch.status = partial)

⚠️ Partially completed

✅ ethereum mainnet token: ETH　target: 0x7d7f...64bb　amount: 0.1 Tx: https://etherscan.io/tx/0x9f86d0... Tx: https://etherscan.io/tx/0xabc123...

❌ solana mainnet token: SOL　target: 5eykt4...2N9d　amount: 1 Reason: insufficient balance

All failed (batch.status = failed)

❌ Test failed

❌ ethereum mainnet token: ETH　target: 0x7d7f...64bb　amount: 0.1 Reason: NO_WALLET_AVAILABLE (no wallet currently available for this chain/network — contact the BadWhale team)

Information-query scenario (does not enter the submit flow)

"Which chains / networks / tokens are supported?"

When the user message matches (support|can use|which|list|available).*(chain|network|token|coin) (or the Chinese equivalents (支持|能用|有哪些|哪些|可用).*(链|网络|币|币种|token|chain|network)) → call GET /health first, then GET /chains on success; do not create a batch, no pre-submit confirmation needed.

Answer using the "Information-query output / Which chains are supported" template below.

Conversation output templates

General format conventions (test-result outputs)

1. The first line carries only the overall status (emoji + short conclusion).
2. One block per task, separated by a blank line.
3. The block's first line marks the task status with an emoji: ✅ completed / ❌ failed / 🚫 cancelled.
4. For a single successful task, use 🔷 on the block's first line.
5. Fixed field order: token → target → amount, using full-width colon ： and full-width space 　 as separators when rendering in Chinese.
6. Each Tx on its own line, showing the full URL (do not use markdown link shorthand).
7. Do not show batchId, do not show elapsed time.

Information-query output

Which chains / networks / tokens are supported

Steps:

python skill/scripts/bw.py health
python skill/scripts/bw.py chains

The output must be split into a Mainnet section and a Testnet section. network === "mainnet" goes under Mainnet; every other network goes under Testnet (e.g. sepolia, nile, testnet).

Fixed table columns:

Rendering rules:

• Chain: the server-returned chain.
• Network: the server-returned network.
• Tokens: all tokens[].token under that network, comma-separated; do not specially mark the native coin unless the user asked about it.
• Availability: available: true → Available; available: false → Unavailable.
• Only show data returned by GET /chains; never fill in from memory.
• If a section has no results, write No mainnet configuration available. or No testnet configuration available.
• By default show all returned items, including available: false (so the customer knows the service supports it but it is currently not submittable).

Filtering rules:

• User specified a token (e.g. "which networks support USDT") → first filter items where tokens[].token equals that token.
• User specified a chain (e.g. "which coins does ethereum support") → first filter by chain.
• Both specified → apply both filters.

Answer template:

Current BadWhale API support:

Mainnet

Chain	Network	Tokens	Availability
ethereum	mainnet	ETH, USDT, USDC	Available
tron	mainnet	TRX, USDT	Unavailable

Testnet

Chain	Network	Tokens	Availability
ethereum	sepolia	ETH, USDT	Available
tron	nile	TRX, USDT	Available

This scenario does not need pre-submit confirmation, because it creates no batch and triggers no on-chain transaction.

Self-check before output:

1. Does it open with Current BadWhale API support: (or its translation)?
2. Are there two sections, Mainnet and Testnet (with the fallback sentence even if a section is empty)?
3. Is the table header exactly Chain | Network | Tokens | Availability (exactly 4 columns)?
4. Are available: false rows included (written as Unavailable), rather than only listing available items?

If any check fails → re-organize the output; do not send it to the user.