SDK Examples

Complete, runnable scripts that perform the full swap flow: register an agent, get a quote, execute a swap, and check the status.

---

CLI (@suwappu/sdk)

The fastest way to interact with Suwappu from your terminal. The @suwappu/sdk package includes a suwappu binary with colored tables, spinners, and interactive swap confirmation.

-str">"hl-comment"># Install
-kw">npm install -g @suwappu/sdk

-str">"hl-comment"># Configure
-kw">export SUWAPPU_API_KEY=suwappu_sk_your_api_key
-str">"hl-comment"># Or: suwappu config set api-key suwappu_sk_your_api_key

-str">"hl-comment"># Use
suwappu chains                       -str">"hl-comment"># List supported chains
suwappu tokens ethereum              -str">"hl-comment"># List tokens on a chain
suwappu prices ETH BTC SOL           -str">"hl-comment"># Token prices with 24h change
suwappu portfolio                    -str">"hl-comment"># Portfolio balances with totals
suwappu swap ETH USDC 0.5 --chain base  -str">"hl-comment"># Quote → confirm → execute
suwappu perps markets                -str">"hl-comment"># Perpetual futures markets
suwappu perps positions 0x1234...    -str">"hl-comment"># Open positions with PnL

-str">"hl-comment"># JSON output for scripting
suwappu prices ETH --json | jq -str">'.[] .priceUsd'

See the full Trading CLI guide for detailed usage and examples.

---

Bash (curl)

-str">"hl-comment">#!/usr/bin/env bash
set -euo pipefail

BASE_URL=-str">"https://api.suwappu.bot/v1/agent"

-str">"hl-comment"># Step 1: Register
-kw">echo -str">"Registering agent..."
REGISTER_RESPONSE=$(-kw">curl -s -X POST -str">"$BASE_URL/register" \
  -H -str">"Content-Type: application/json" \
  -d -str">'{-str">"name":-str">"my-trading-bot",-str">"description":-str">"Automated trading agent"}')

API_KEY=$(-kw">echo -str">"$REGISTER_RESPONSE" | jq -r -str">'.agent.api_key')
AGENT_ID=$(-kw">echo -str">"$REGISTER_RESPONSE" | jq -r -str">'.agent.id')
-kw">echo -str">"Agent registered: $AGENT_ID"
-kw">echo -str">"API key: $API_KEY"

-str">"hl-comment"># Step 2: Get a quote
-kw">echo -str">""
-kw">echo -str">"Requesting quote..."
QUOTE_RESPONSE=$(-kw">curl -s -X POST -str">"$BASE_URL/quote" \
  -H -str">"Content-Type: application/json" \
  -H -str">"Authorization: Bearer $API_KEY" \
  -d -str">'{
    -str">"from_token": -str">"USDC",
    -str">"to_token": -str">"ETH",
    -str">"amount": -str">"500.00",
    -str">"chain": -str">"ethereum"
  }')

QUOTE_ID=$(-kw">echo -str">"$QUOTE_RESPONSE" | jq -r -str">'.quote.quote_id')
AMOUNT_OUT=$(-kw">echo -str">"$QUOTE_RESPONSE" | jq -r -str">'.quote.amount_out')
EXPIRES=$(-kw">echo -str">"$QUOTE_RESPONSE" | jq -r -str">'.quote.expires_in_seconds')
-kw">echo -str">"Quote ID: $QUOTE_ID"
-kw">echo -str">"You will receive: $AMOUNT_OUT ETH"
-kw">echo -str">"Quote expires in: ${EXPIRES}s"

-str">"hl-comment"># Step 3: Execute the swap
-kw">echo -str">""
-kw">echo -str">"Executing swap..."
SWAP_RESPONSE=$(-kw">curl -s -X POST -str">"$BASE_URL/swap/execute" \
  -H -str">"Content-Type: application/json" \
  -H -str">"Authorization: Bearer $API_KEY" \
  -d -str">"{\"quote_id\-str">": \"$QUOTE_ID\-str">"}")

SWAP_ID=$(-kw">echo -str">"$SWAP_RESPONSE" | jq -r -str">'.swap.swap_id')
TX_HASH=$(-kw">echo -str">"$SWAP_RESPONSE" | jq -r -str">'.swap.tx_hash')
-kw">echo -str">"Swap ID: $SWAP_ID"
-kw">echo -str">"Tx hash: $TX_HASH"

-str">"hl-comment"># Step 4: Poll for completion
-kw">echo -str">""
-kw">echo -str">"Checking status..."
for i in $(seq 1 10); do
  STATUS_RESPONSE=$(-kw">curl -s -X GET -str">"$BASE_URL/swap/status/$SWAP_ID" \
    -H -str">"Authorization: Bearer $API_KEY")

  STATUS=$(-kw">echo -str">"$STATUS_RESPONSE" | jq -r -str">'.swap.status')
  -kw">echo -str">"  Attempt $i: status=$STATUS"

  if [ -str">"$STATUS" = -str">"completed" ] || [ -str">"$STATUS" = -str">"failed" ]; then
    -kw">echo -str">""
    -kw">echo -str">"$STATUS_RESPONSE" | jq .
    break
  fi

  sleep 2
done

---

Python

Requires Python 3.7+ and the requests library (pip install requests).

class=class="hl-str">"hl-comment">#!/usr/bin/env python3
class="hl-str">""class="hl-str">"Suwappu Agent API — full swap flow example."class="hl-str">""

import time
import requests

BASE_URL = class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent"


def main():
    class=class="hl-str">"hl-comment"># Step 1: Register
    print(class="hl-str">"Registering agent...")
    register_resp = requests.post(
        fclass="hl-str">"{BASE_URL}/register",
        json={
            class="hl-str">"name": class="hl-str">"my-trading-bot",
            class="hl-str">"description": class="hl-str">"Automated trading agent",
        },
    )
    register_resp.raise_for_status()
    register_data = register_resp.json()

    api_key = register_data[class="hl-str">"agent"][class="hl-str">"api_key"]
    agent_id = register_data[class="hl-str">"agent"][class="hl-str">"id"]
    print(fclass="hl-str">"Agent registered: {agent_id}")
    print(fclass="hl-str">"API key: {api_key}")

    headers = {
        class="hl-str">"Content-Type": class="hl-str">"application/json",
        class="hl-str">"Authorization": fclass="hl-str">"Bearer {api_key}",
    }

    class=class="hl-str">"hl-comment"># Step 2: Get a quote
    print(class="hl-str">"\nRequesting quote...")
    quote_resp = requests.post(
        fclass="hl-str">"{BASE_URL}/quote",
        headers=headers,
        json={
            class="hl-str">"from_token": class="hl-str">"USDC",
            class="hl-str">"to_token": class="hl-str">"ETH",
            class="hl-str">"amount": class="hl-str">"500.00",
            class="hl-str">"chain": class="hl-str">"ethereum",
        },
    )
    quote_resp.raise_for_status()
    quote_data = quote_resp.json()

    quote_id = quote_data[class="hl-str">"quote"][class="hl-str">"quote_id"]
    amount_out = quote_data[class="hl-str">"quote"][class="hl-str">"amount_out"]
    expires = quote_data[class="hl-str">"quote"][class="hl-str">"expires_in_seconds"]
    print(fclass="hl-str">"Quote ID: {quote_id}")
    print(fclass="hl-str">"You will receive: {amount_out} ETH")
    print(fclass="hl-str">"Quote expires in: {expires}s")

    class=class="hl-str">"hl-comment"># Step 3: Execute the swap
    print(class="hl-str">"\nExecuting swap...")
    swap_resp = requests.post(
        fclass="hl-str">"{BASE_URL}/swap/execute",
        headers=headers,
        json={class="hl-str">"quote_id": quote_id},
    )
    swap_resp.raise_for_status()
    swap_data = swap_resp.json()

    swap_id = swap_data[class="hl-str">"swap"][class="hl-str">"swap_id"]
    tx_hash = swap_data[class="hl-str">"swap"][class="hl-str">"tx_hash"]
    print(fclass="hl-str">"Swap ID: {swap_id}")
    print(fclass="hl-str">"Tx hash: {tx_hash}")

    class=class="hl-str">"hl-comment"># Step 4: Poll for completion
    print(class="hl-str">"\nChecking status...")
    for attempt in range(1, 11):
        status_resp = requests.get(
            fclass="hl-str">"{BASE_URL}/swap/status/{swap_id}",
            headers=headers,
        )
        status_resp.raise_for_status()
        status_data = status_resp.json()

        status = status_data[class="hl-str">"swap"][class="hl-str">"status"]
        print(fclass="hl-str">"  Attempt {attempt}: status={status}")

        if status in (class="hl-str">"completed", class="hl-str">"failed"):
            print()
            import json
            print(json.dumps(status_data, indent=2))
            break

        time.sleep(2)


if __name__ == class="hl-str">"__main__":
    main()

---

TypeScript

Requires Node.js 18+ (for native fetch). No external dependencies needed.

class=class="hl-str">"hl-comment">// suwappu-swap.ts
class=class="hl-str">"hl-comment">// Run with: npx tsx suwappu-swap.ts

const BASE_URL = class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent";

interface RegisterResponse {
  success: boolean;
  agent: {
    id: string;
    name: string;
    api_key: string;
    created_at: string;
  };
}

interface QuoteResponse {
  success: boolean;
  quote: {
    quote_id: string;
    from_token: string;
    to_token: string;
    amount_in: string;
    amount_out: string;
    exchange_rate: string;
    price_impact: string;
    fee: string;
    expires_in_seconds: number;
  };
}

interface SwapResponse {
  success: boolean;
  swap: {
    swap_id: string;
    status: string;
    tx_hash: string;
    from_token: string;
    to_token: string;
    amount_in: string;
    amount_out: string;
    created_at: string;
  };
}

interface StatusResponse {
  success: boolean;
  swap: {
    swap_id: string;
    status: string;
    tx_hash: string;
    from_token: string;
    to_token: string;
    amount_in: string;
    amount_out: string;
    chain: string;
    created_at: string;
    completed_at?: string;
  };
}

async function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function main(): Promise<void> {
  class=class="hl-str">"hl-comment">// Step 1: Register
  console.log(class="hl-str">"Registering agent...");
  const registerResp = await fetch(${BASE_URL}/register, {
    method: class="hl-str">"POST",
    headers: { class="hl-str">"Content-Type": class="hl-str">"application/json" },
    body: JSON.stringify({
      name: class="hl-str">"my-trading-bot",
      description: class="hl-str">"Automated trading agent",
    }),
  });

  if (!registerResp.ok) {
    throw new Error(Registration failed: ${registerResp.status});
  }

  const registerData: RegisterResponse = await registerResp.json();
  const apiKey = registerData.agent.api_key;
  console.log(Agent registered: ${registerData.agent.id});
  console.log(API key: ${apiKey});

  const headers = {
    class="hl-str">"Content-Type": class="hl-str">"application/json",
    Authorization: Bearer ${apiKey},
  };

  class=class="hl-str">"hl-comment">// Step 2: Get a quote
  console.log(class="hl-str">"\nRequesting quote...");
  const quoteResp = await fetch(${BASE_URL}/quote, {
    method: class="hl-str">"POST",
    headers,
    body: JSON.stringify({
      from_token: class="hl-str">"USDC",
      to_token: class="hl-str">"ETH",
      amount: class="hl-str">"500.00",
      chain: class="hl-str">"ethereum",
    }),
  });

  if (!quoteResp.ok) {
    throw new Error(Quote request failed: ${quoteResp.status});
  }

  const quoteData: QuoteResponse = await quoteResp.json();
  const quoteId = quoteData.quote.quote_id;
  console.log(Quote ID: ${quoteId});
  console.log(You will receive: ${quoteData.quote.amount_out} ETH);
  console.log(Quote expires in: ${quoteData.quote.expires_in_seconds}s);

  class=class="hl-str">"hl-comment">// Step 3: Execute the swap
  console.log(class="hl-str">"\nExecuting swap...");
  const swapResp = await fetch(${BASE_URL}/swap/execute, {
    method: class="hl-str">"POST",
    headers,
    body: JSON.stringify({ quote_id: quoteId }),
  });

  if (!swapResp.ok) {
    throw new Error(Swap execution failed: ${swapResp.status});
  }

  const swapData: SwapResponse = await swapResp.json();
  const swapId = swapData.swap.swap_id;
  console.log(Swap ID: ${swapId});
  console.log(Tx hash: ${swapData.swap.tx_hash});

  class=class="hl-str">"hl-comment">// Step 4: Poll for completion
  console.log(class="hl-str">"\nChecking status...");
  for (let attempt = 1; attempt <= 10; attempt++) {
    const statusResp = await fetch(${BASE_URL}/swap/status/${swapId}, {
      headers,
    });

    if (!statusResp.ok) {
      throw new Error(Status check failed: ${statusResp.status});
    }

    const statusData: StatusResponse = await statusResp.json();
    const status = statusData.swap.status;
    console.log(  Attempt ${attempt}: status=${status});

    if (status === class="hl-str">"completed" || status === class="hl-str">"failed") {
      console.log();
      console.log(JSON.stringify(statusData, null, 2));
      break;
    }

    await sleep(2000);
  }
}

main().catch((err) => {
  console.error(class="hl-str">"Error:", err.message);
  process.exit(1);
});