@xstocker/agent-sdk

SDK for AI agents to trade tokenized U.S. stocks (xStocks) on Solana.

No account. No API key. No OAuth. This SDK only reads public data and builds unsigned transactions — it never touches a private key. You (or your agent framework's wallet adapter) are responsible for signing and broadcasting the returned transaction.

Install

npm install @xstocker/agent-sdk

Usage

import { xstocker } from "@xstocker/agent-sdk";

// 1. Discover tradable assets
const { assets, payTokens } = await xstocker.getAssets();

// 2. Build an unsigned buy transaction
const order = await xstocker.buildOrder({
  wallet: "USER_SOLANA_ADDRESS",
  asset: "NVDAx",
  amount: 100,
  payToken: "USDC", // or "SOL"
  side: "buy",       // or "sell"
});

console.log(order.details);
// { side: 'buy', asset: 'NVDAx', amountIn: '100 USDC',
//   expectedOut: '0.470123 NVDAx', fee: '0.002350 NVDAx', ... }

// 3a. If your agent CAN sign transactions programmatically (e.g. it has its
//     own wallet adapter), sign order.transaction (base64) with the user's
//     own wallet, then broadcast it to Solana yourself.

// 3b. If your agent CANNOT sign transactions (e.g. a plain chat bot with no
//     wallet access), just hand the user order.confirmUrl instead — it opens
//     a page where they connect their own wallet and sign in-browser:
console.log(order.confirmUrl);
// "https://xstocker.com/agents?asset=NVDAx&amount=100&pay_token=USDC&side=buy"

// 4. Verify it landed
const status = await xstocker.getOrderStatus(signature);
console.log(status.status); // "confirmed" | "finalized" | "processed" | "failed" | "not_found"

Selling

await xstocker.buildOrder({
  wallet: "USER_SOLANA_ADDRESS",
  asset: "NVDAx",
  amount: 0.5,        // amount of NVDAx to sell
  payToken: "USDC",   // token you receive
  side: "sell",
});

Referral partners

// Register once — get a partner_id
const { partner_id } = await xstocker.registerPartner("YOUR_PAYOUT_WALLET_ADDRESS");

// Include it on every buildOrder() call — adds a small extra fee that
// accrues to your wallet, on top of the standard platform fee.
const order = await xstocker.buildOrder({
  wallet: "USER_SOLANA_ADDRESS",
  asset: "NVDAx",
  amount: 100,
  partnerId: partner_id,
});

// Confirm your earnings once the trade actually lands on-chain
await xstocker.getOrderStatus(signature, order.details.partnerRef);

// Check accrued earnings anytime
const info = await xstocker.getPartnerInfo(partner_id);
console.log(info.commission, info.availableToWithdraw);

Custom client

import { XStockerAgentClient } from "@xstocker/agent-sdk";

const client = new XStockerAgentClient({ baseUrl: "https://api.xstocker.com" });

Error handling

import { XStockerAgentError } from "@xstocker/agent-sdk";

try {
  await xstocker.buildOrder({ wallet, asset: "NVDAx", amount: 100 });
} catch (err) {
  if (err instanceof XStockerAgentError) {
    console.error(err.code, err.message); // e.g. "no_route", "invalid_wallet"
  }
}

Links

• Agent API landing page
• OpenAPI spec
• agent.json

License

MIT