feat: add trending tokens and swaps REST API endpoint support

Co-Authored-By: unknown <>

Author: devin-ai-integration[bot]

src/cli.ts

@@ -7,6 +7,8 @@ import {
   listingsCommand,
   nftsCommand,
   offersCommand,
+  swapsCommand,
+  tokensCommand,
 } from "./commands/index.js"
 
 const BANNER = `
@@ -65,6 +67,8 @@ program.addCommand(listingsCommand(getClient, getFormat))
 program.addCommand(offersCommand(getClient, getFormat))
 program.addCommand(eventsCommand(getClient, getFormat))
 program.addCommand(accountsCommand(getClient, getFormat))
+program.addCommand(tokensCommand(getClient, getFormat))
+program.addCommand(swapsCommand(getClient, getFormat))
 
 program.hook("postAction", () => {})
 

src/commands/index.ts

@@ -4,3 +4,5 @@ export { eventsCommand } from "./events.js"
 export { listingsCommand } from "./listings.js"
 export { nftsCommand } from "./nfts.js"
 export { offersCommand } from "./offers.js"
+export { swapsCommand } from "./swaps.js"
+export { tokensCommand } from "./tokens.js"

src/commands/swaps.ts

@@ -0,0 +1,71 @@
+import { Command } from "commander"
+import type { OpenSeaClient } from "../client.js"
+import { formatOutput } from "../output.js"
+import type { SwapQuoteResponse } from "../types/index.js"
+
+export function swapsCommand(
+  getClient: () => OpenSeaClient,
+  getFormat: () => "json" | "table",
+): Command {
+  const cmd = new Command("swaps").description(
+    "Get swap quotes for token trading",
+  )
+
+  cmd
+    .command("quote")
+    .description(
+      "Get a quote for swapping tokens, including price details and executable transaction data",
+    )
+    .requiredOption("--from-chain <chain>", "Chain of the token to swap from")
+    .requiredOption(
+      "--from-address <address>",
+      "Contract address of the token to swap from",
+    )
+    .requiredOption("--to-chain <chain>", "Chain of the token to swap to")
+    .requiredOption(
+      "--to-address <address>",
+      "Contract address of the token to swap to",
+    )
+    .requiredOption("--quantity <quantity>", "Amount to swap (in token units)")
+    .requiredOption("--address <address>", "Wallet address executing the swap")
+    .option(
+      "--slippage <slippage>",
+      "Slippage tolerance (0.0 to 0.5, default: 0.01)",
+    )
+    .option(
+      "--recipient <recipient>",
+      "Recipient address (defaults to sender address)",
+    )
+    .action(
+      async (options: {
+        fromChain: string
+        fromAddress: string
+        toChain: string
+        toAddress: string
+        quantity: string
+        address: string
+        slippage?: string
+        recipient?: string
+      }) => {
+        const client = getClient()
+        const result = await client.get<SwapQuoteResponse>(
+          "/api/v2/swap/quote",
+          {
+            from_chain: options.fromChain,
+            from_address: options.fromAddress,
+            to_chain: options.toChain,
+            to_address: options.toAddress,
+            quantity: options.quantity,
+            address: options.address,
+            slippage: options.slippage
+              ? Number.parseFloat(options.slippage)
+              : undefined,
+            recipient: options.recipient,
+          },
+        )
+        console.log(formatOutput(result, getFormat()))
+      },
+    )
+
+  return cmd
+}

src/commands/tokens.ts

@@ -0,0 +1,70 @@
+import { Command } from "commander"
+import type { OpenSeaClient } from "../client.js"
+import { formatOutput } from "../output.js"
+import type { Chain, Token, TokenDetails } from "../types/index.js"
+
+export function tokensCommand(
+  getClient: () => OpenSeaClient,
+  getFormat: () => "json" | "table",
+): Command {
+  const cmd = new Command("tokens").description(
+    "Query trending tokens, top tokens, and token details",
+  )
+
+  cmd
+    .command("trending")
+    .description("Get trending tokens based on OpenSea's trending score")
+    .option("--chains <chains>", "Comma-separated list of chains to filter by")
+    .option("--limit <limit>", "Number of results (max 100)", "20")
+    .option("--cursor <cursor>", "Pagination cursor")
+    .action(
+      async (options: { chains?: string; limit: string; cursor?: string }) => {
+        const client = getClient()
+        const result = await client.get<{ tokens: Token[]; next?: string }>(
+          "/api/v2/tokens/trending",
+          {
+            chains: options.chains,
+            limit: Number.parseInt(options.limit, 10),
+            cursor: options.cursor,
+          },
+        )
+        console.log(formatOutput(result, getFormat()))
+      },
+    )
+
+  cmd
+    .command("top")
+    .description("Get top tokens ranked by 24-hour trading volume")
+    .option("--chains <chains>", "Comma-separated list of chains to filter by")
+    .option("--limit <limit>", "Number of results (max 100)", "20")
+    .option("--cursor <cursor>", "Pagination cursor")
+    .action(
+      async (options: { chains?: string; limit: string; cursor?: string }) => {
+        const client = getClient()
+        const result = await client.get<{ tokens: Token[]; next?: string }>(
+          "/api/v2/tokens/top",
+          {
+            chains: options.chains,
+            limit: Number.parseInt(options.limit, 10),
+            cursor: options.cursor,
+          },
+        )
+        console.log(formatOutput(result, getFormat()))
+      },
+    )
+
+  cmd
+    .command("get")
+    .description("Get detailed information about a specific token")
+    .argument("<chain>", "Blockchain chain")
+    .argument("<address>", "Token contract address")
+    .action(async (chain: string, address: string) => {
+      const client = getClient()
+      const result = await client.get<TokenDetails>(
+        `/api/v2/chain/${chain as Chain}/token/${address}`,
+      )
+      console.log(formatOutput(result, getFormat()))
+    })
+
+  return cmd
+}

src/sdk.ts

@@ -13,6 +13,9 @@ import type {
   NFT,
   Offer,
   OpenSeaClientConfig,
+  SwapQuoteResponse,
+  Token,
+  TokenDetails,
 } from "./types/index.js"
 
 export class OpenSeaCLI {
@@ -24,6 +27,8 @@ export class OpenSeaCLI {
   readonly offers: OffersAPI
   readonly events: EventsAPI
   readonly accounts: AccountsAPI
+  readonly tokens: TokensAPI
+  readonly swaps: SwapsAPI
 
   constructor(config: OpenSeaClientConfig) {
     this.client = new OpenSeaClient(config)
@@ -33,6 +38,8 @@ export class OpenSeaCLI {
     this.offers = new OffersAPI(this.client)
     this.events = new EventsAPI(this.client)
     this.accounts = new AccountsAPI(this.client)
+    this.tokens = new TokensAPI(this.client)
+    this.swaps = new SwapsAPI(this.client)
   }
 }
 
@@ -291,3 +298,61 @@ class AccountsAPI {
     return this.client.get(`/api/v2/accounts/${address}`)
   }
 }
+
+class TokensAPI {
+  constructor(private client: OpenSeaClient) {}
+
+  async trending(options?: {
+    limit?: number
+    chains?: string[]
+    cursor?: string
+  }): Promise<{ tokens: Token[]; next?: string }> {
+    return this.client.get("/api/v2/tokens/trending", {
+      limit: options?.limit,
+      chains: options?.chains?.join(","),
+      cursor: options?.cursor,
+    })
+  }
+
+  async top(options?: {
+    limit?: number
+    chains?: string[]
+    cursor?: string
+  }): Promise<{ tokens: Token[]; next?: string }> {
+    return this.client.get("/api/v2/tokens/top", {
+      limit: options?.limit,
+      chains: options?.chains?.join(","),
+      cursor: options?.cursor,
+    })
+  }
+
+  async get(chain: Chain, address: string): Promise<TokenDetails> {
+    return this.client.get(`/api/v2/chain/${chain}/token/${address}`)
+  }
+}
+
+class SwapsAPI {
+  constructor(private client: OpenSeaClient) {}
+
+  async quote(options: {
+    fromChain: string
+    fromAddress: string
+    toChain: string
+    toAddress: string
+    quantity: string
+    address: string
+    slippage?: number
+    recipient?: string
+  }): Promise<SwapQuoteResponse> {
+    return this.client.get("/api/v2/swap/quote", {
+      from_chain: options.fromChain,
+      from_address: options.fromAddress,
+      to_chain: options.toChain,
+      to_address: options.toAddress,
+      quantity: options.quantity,
+      address: options.address,
+      slippage: options.slippage,
+      recipient: options.recipient,
+    })
+  }
+}

src/types/api.ts

@@ -254,3 +254,70 @@ export interface PaginatedResponse<T> {
   next?: string
   results: T[]
 }
+
+export interface Token {
+  address: string
+  chain: string
+  name: string
+  symbol: string
+  image_url?: string
+  usd_price: string
+  decimals: number
+  market_cap_usd?: number
+  volume_24h?: number
+  price_change_24h?: number
+  opensea_url: string
+}
+
+export interface TokenDetails {
+  address: string
+  chain: string
+  name: string
+  symbol: string
+  image_url?: string
+  description?: string
+  usd_price: string
+  decimals: number
+  stats?: TokenStats
+  socials?: TokenSocials
+  opensea_url: string
+}
+
+export interface TokenStats {
+  market_cap_usd?: number
+  fdv_usd?: number
+  circulating_supply?: number
+  max_supply?: number
+  total_supply?: number
+  volume_24h?: number
+  price_change_1h?: number
+  price_change_24h?: number
+  price_change_7d?: number
+  price_change_30d?: number
+}
+
+export interface TokenSocials {
+  website?: string
+  twitter_handle?: string
+  telegram_identifier?: string
+}
+
+export interface SwapQuote {
+  total_price_usd: number
+  total_cost_usd: number
+  slippage_tolerance: number
+  estimated_duration_ms: number
+  marketplace_fee_bps: number
+}
+
+export interface SwapTransaction {
+  chain: string
+  to?: string
+  data: string
+  value?: string
+}
+
+export interface SwapQuoteResponse {
+  quote: SwapQuote
+  transactions: SwapTransaction[]
+}