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 — reads the static list at
//    https://xstocker.com/agent/assets.json (CDN file, no API call)
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 and send it. It expires after roughly a minute, so build it
//     right before signing and rebuild if it runs out.

// 3b. If your agent CANNOT sign transactions (e.g. a plain chat bot with no
//     wallet access), hand the user order.solanaPayUrl instead, as a link or
//     a QR code. Their wallet (e.g. Phantom) opens it and requests a fresh
//     transaction at the moment they approve, so nothing expires in between:
console.log(order.solanaPayUrl);
// "solana:https%3A%2F%2Fxstocker.com%2Fagent%2Fpay%3Fasset%3DNVDAx%26amount%3D100..."
// (not returned when partnerId is used — see Referral partners)

// 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",
});

On a sell, amount is in the units the wallet shows (xStocks are scaled-UI tokens, so this can differ from the raw on-chain amount; the API converts it). Pass a number, or a decimal string for up to 8 decimals. The API never sells more than the wallet holds.

Sell everything

const order = await xstocker.buildOrder({
  wallet: "USER_SOLANA_ADDRESS",
  asset: "NVDAx",
  amount: "max",      // sell the entire balance (sells only)
  side: "sell",
});

console.log(order.details.amountIn); // e.g. "3.12345678 NVDAx" — what was actually sold

With "max" the API reads the exact on-chain balance itself, so you do not need to look it up (and there is no rounding dust left behind).

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" });

Assets

getAssets() reads a static file from the CDN, not the API. asset in buildOrder() accepts the ticker in any letter case (the trailing "x" is optional) or the token's mint address.

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"
  }
}