Stellar DevKit documentation

Overview

The Stellar DevKit is a developer suite for building on Stellar: DEX swaps (SoroSwap aggregator), payments, path payments, lending (Blend), oracles (Reflector), AI agents with tools, MCP for Cursor/Claude, and HTTP 402 payment-gated APIs.

• stellar-agent-kit — Unified SDK: getBalances, sendPayment, createAccount, pathPayment, dexGetQuote, dexSwap, getPrice, lendingSupply/lendingBorrow.
• x402-stellar-sdk — Monetize APIs with Stellar payments: server middleware (Express/Hono/Next) and client x402Fetch with payWithStellar.
• stellar-devkit-mcp — MCP server: get_stellar_contract, get_sdk_snippet, get_quote, list_devkit_methods.
• create-stellar-devkit-app — CLI to scaffold agent-kit (Next.js + StellarAgentKit) or x402-api (Express + paywall).

Network: mainnet only for stellar-agent-kit DEX/lending. x402 supports testnet and mainnet.

Package Summary

Getting Started

Install the SDK, set environment variables, then create an agent and call initialize() before any protocol method. Or scaffold an app with the CLI.

Quick start

Install the SDK, set env vars, then create an agent and call initialize() before any protocol method.

npm install stellar-agent-kit

Required env (e.g. in .env):

• SECRET_KEY — Stellar secret key (S...). Keep server-side only.
• SOROSWAP_API_KEY — Required for DEX quotes (get from SoroSwap aggregator).

import { StellarAgentKit, MAINNET_ASSETS } from "stellar-agent-kit";

const agent = new StellarAgentKit(process.env.SECRET_KEY!, "mainnet");
await agent.initialize();

// Get a swap quote (1 XLM → USDC, 7 decimals)
const quote = await agent.dexGetQuote(
  { contractId: MAINNET_ASSETS.XLM.contractId },
  { contractId: MAINNET_ASSETS.USDC.contractId },
  "10000000"
);
const result = await agent.dexSwap(quote);
console.log(result.hash);

Or scaffold an app: npx create-stellar-devkit-app my-app and choose agent-kit or x402-api.

stellar-agent-kit

npm install stellar-agent-kit. One class StellarAgentKit(secretKey, network); call await agent.initialize() once, then use methods below.

Supported Protocols

getBalances(accountId?)

Native + trustline balances. Omit accountId to use the agent's public key.

const balances = await agent.getBalances();
// or: await agent.getBalances("G...");
// → [{ assetCode: "XLM", balance: "100.5", issuer?: string, limit?: string }, ...]

sendPayment(to, amount, assetCode?, assetIssuer?)

Send XLM or custom asset. Omit asset for native XLM.

await agent.sendPayment("G...", "10");
await agent.sendPayment("G...", "5", "USDC", "G...");  // custom asset
// → { hash: "..." }

createAccount(destination, startingBalance)

Create and fund a new account (minimum ~1 XLM for base reserve).

await agent.createAccount("G...", "1");
// → { hash: "..." }

pathPayment(sendAsset, sendMax, destination, destAsset, destAmount, path?)

Path payment strict receive: send up to sendMax of sendAsset so destination receives exactly destAmount of destAsset.

await agent.pathPayment(
  { assetCode: "XLM" },           // send asset
  "10",                           // sendMax
  "G...",                         // destination
  { assetCode: "USDC", issuer: "G..." },  // dest asset
  "5",                            // destAmount
  []                              // optional path
);
// → { hash: "..." }

dexGetQuote(fromAsset, toAsset, amount) / dexSwap(quote) / dexSwapExactIn(...)

SoroSwap aggregator. Amount in smallest units (e.g. 7 decimals for XLM).

const quote = await agent.dexGetQuote(
  { contractId: MAINNET_ASSETS.XLM.contractId },
  { contractId: MAINNET_ASSETS.USDC.contractId },
  "10000000"  // 1 XLM
);
await agent.dexSwap(quote);

// Or one-shot:
await agent.dexSwapExactIn(fromAsset, toAsset, amount);

getPrice(asset)

Reflector oracle. Asset: { symbol: "XLM" } or { contractId: "C..." }.

const price = await agent.getPrice({ symbol: "XLM" });
// → PriceData

lendingSupply(args) / lendingBorrow(args)

Blend protocol. See exported types LendingSupplyArgs, LendingBorrowArgs.

await agent.lendingSupply({ ... });
await agent.lendingBorrow({ ... });

x402-stellar-sdk

npm install x402-stellar-sdk. Protect routes with a Stellar payment; client detects 402 and can retry with payWithStellar.

Features

• Paywall middleware: return HTTP 402 with payment details (amount, asset, destination, network).
• Server integrations: Express, Hono, Next.js App Router.
• Client x402Fetch: on 402, calls payWithStellar, retries with X-402-Transaction-Hash.
• Horizon-based verification of payment before serving content.
• Supports mainnet and testnet; native XLM or custom assets (e.g. USDC).

Server options (X402StellarOptions)

• price — Amount string (e.g. "1", "10.5")
• assetCode — e.g. "XLM", "USDC"
• issuer? — For custom assets; omit for native XLM
• network — "mainnet" | "testnet"
• destination — Stellar account (G...) that receives payment
• memo? — Optional memo for correlation

Express

import express from "express";
import { x402 } from "x402-stellar-sdk/server";

const app = express();
const options = {
  price: "1",
  assetCode: "XLM",
  network: "testnet",
  destination: process.env.X402_DESTINATION!,
  memo: "premium-api",
};
app.use("/api/premium", x402(options));
app.get("/api/premium", (_, res) => res.json({ data: "Premium content" }));
app.listen(3000);

Hono

import { Hono } from "hono";
import { x402Hono } from "x402-stellar-sdk/server/hono";

const app = new Hono();
app.use("/api/premium", x402Hono(options));
app.get("/api/premium", (c) => c.json({ data: "Premium content" }));

Next.js App Router

// app/api/premium/route.ts
import { withX402 } from "x402-stellar-sdk/server/next";

export async function GET(req: Request) {
  const res402 = await withX402(req.headers, options);
  if (res402) return res402;
  return Response.json({ data: "Premium content" });
}

Client: x402Fetch

On 402, the client must provide payWithStellar to perform the payment and return the transaction hash; then the request is retried with X-402-Transaction-Hash.

import { x402Fetch } from "x402-stellar-sdk/client";
import type { X402PaymentRequest, X402PaymentResponse } from "x402-stellar-sdk/client";

const res = await x402Fetch(url, undefined, {
  payWithStellar: async (req: X402PaymentRequest): Promise<X402PaymentResponse | null> => {
    // req: amount, assetCode, network, destination, memo?
    // Submit payment (e.g. Freighter), then:
    return { transactionHash: txHash };
  },
});
const data = await res.json();

create-stellar-devkit-app

npx create-stellar-devkit-app [name]. Prompts for project name and template if not provided.

npx create-stellar-devkit-app my-app
npx create-stellar-devkit-app my-app --agent-kit
npx create-stellar-devkit-app my-api --x402-api
npx create-stellar-devkit-app my-app --skip-install

Templates

• agent-kit — Next.js app with stellar-agent-kit: quote API route, swap UI. Env: SECRET_KEY, SOROSWAP_API_KEY.
• x402-api — Express server with one premium route. Env: X402_DESTINATION (your G...), NETWORK (testnet|mainnet).

stellar-devkit-mcp

npm install stellar-devkit-mcp. MCP server for Cursor/Claude: tools and resources for Stellar contracts and SDK snippets.

Tools

• get_stellar_contract — protocol (e.g. soroswap), network (mainnet). Returns contract ID.
• get_sdk_snippet — operation: swap, quote, x402-server, x402-client, get-balances, send-payment, create-account, path-payment. Returns copy-paste code.
• get_quote — fromAsset, toAsset, amount. Live quote (requires SOROSWAP_API_KEY where MCP runs).
• list_devkit_methods — Lists StellarAgentKit and x402-stellar-sdk public APIs.

Add to Cursor MCP config; use a new chat so tools are attached. See DevKit → MCP tab.

CLI

From repo root after npm run build:root (or full build). Commands live in src/ and are run via node dist/index.js <command>.

balance

node dist/index.js balance GABC... [--network=testnet|mainnet]
# Output: JSON array of { code, issuer, balance }

pay

node dist/index.js pay <SECRET_KEY> <DESTINATION_G...> <amount> [--network=mainnet] [--asset=USDC] [--issuer=G...]

agent

Interactive chat with tools: check_balance, swap_asset, get_swap_quote, create_trustline. Uses GROQ_API_KEY or --api-key (OpenAI-compatible).

node dist/index.js agent [--api-key <key>]
# At prompt: "What's the balance of G...?" or "Get a quote to swap 10 XLM to USDC"

UI & APIs

This app (Orbit) provides Swap and Send with Freighter; the backend builds transactions and you sign in the wallet. No secret key in the browser.

Swap

• POST /api/swap/quote — Body: from, to, amount, network. Returns quote.
• POST /api/swap/build — Build swap transaction.
• POST /api/swap/submit — Submit signed transaction.

Send

• POST /api/send/build — Build payment transaction.
• POST /api/send/submit — Submit signed payment.

Other

• GET /api/balance?address=...&network=... — Account balances.
• GET /api/price — Price endpoint (if implemented).
• GET /api/v1/validate?appId=... — DevKit project validation.

DevKit: create project (APP Id, API endpoint), Protocols, Code generator, MCP tab.

Environment reference

Networks & Contracts

Stellar mainnet and testnet endpoints used by the DevKit. Contract and asset IDs are for mainnet unless noted.

Networks

Contract addresses (mainnet)

Token / asset addresses (mainnet)

Use MAINNET_ASSETS from stellar-agent-kit in code.

Project structure

Monorepo layout. Packages are under packages/; UI and SDK frontend under ui/ and sdk-fe/.

stellar-agent-kit/
├── packages/
│   ├── x402-stellar-sdk/     # HTTP 402 server + client
│   ├── stellar-agent-kit/    # DeFi SDK (DEX, lending, oracles)
│   ├── create-stellar-devkit-app/  # CLI + templates
│   └── stellar-devkit-mcp/   # MCP server
├── ui/                       # Next.js app (Orbit)
├── sdk-fe/                   # SDK docs / package pages
└── docs/                     # REFERENCE_MANTLE_DEVKIT, etc.

Development

From the repo root. Use npm run build:root or full build before running CLI or MCP.

• npm install — Install dependencies (root + workspaces).
• npm run build / npm run build:root — Build packages and CLI.
• npm run typecheck — TypeScript check.
• npm run lint — Lint.
• npm run dev — Run UI dev server (e.g. ui/ or root script).

Links

• Docs — This documentation.
• DevKit — Create project, Protocols, Code generator, MCP.
• Try Swap — Swap UI with Freighter.
• Pricing — Plans and Dodo Payments.
• Stellar docs: developers.stellar.org.
• Explorer: stellar.expert.