POST /trading/swap

Execute a buy or sell on every wallet in the list.

Fan-out swap: each wallet signs its own tx. Per-wallet failures don't abort the batch — check aResults[].success per row. Auto-resolves pool + DEX from sTokenAddress.

Use case

Manual trading action from the UI — e.g. "sell 50% of holdings across all sniper wallets" or "buy 0.1 SOL each from 20 wallets".

Body

Field	Type	Required	Description
sTokenAddress	string	yes	Token mint.
aWalletAddresses	string[]	yes	1–50 pubkeys, each user-owned. Duplicates rejected.
eSwapType	BUY | SELL	yes	Direction.
eSwapValueType	EXACT | PERCENTAGE	yes	How to interpret nValue.
nValue	number	yes	> 0. Must be <= 100 when PERCENTAGE.

Semantics

eSwapType	eSwapValueType	Meaning
BUY	EXACT	nValue SOL spent by each wallet.
BUY	PERCENTAGE	nValue% of each wallet's SOL balance.
SELL	EXACT	nValue token units (UI) sold by each wallet.
SELL	PERCENTAGE	nValue% of each wallet's token balance.

Response 200

{
  "success": true,
  "eSwapType": "BUY",
  "eSwapValueType": "PERCENTAGE",
  "nValue": 10,
  "sTokenAddress": "…",
  "aResults": [
    { "sWalletAddress": "wallet1", "signature": "3k…", "success": true },
    {
      "sWalletAddress": "wallet2",
      "signature": null,
      "success": false,
      "reason": "insufficient SOL",
      "required": 5050000,
      "current": 0
    }
  ],
  "stats": { "requested": 2, "eligible": 1, "succeeded": 1, "failed": 1 }
}

reason values

Reason	Meaning
swap failed on-chain	Tx submitted, rejected by network.
insufficient SOL	Buy-side wallet didn't have enough SOL.
insufficient SOL for tx fees	Sell-side wallet can't cover fees.
insufficient token balance	Sell-side wallet doesn't hold enough of the token.
wallet dropped during prepare step	Defensive fallback.

Top-level success is true when at least one wallet landed.

Errors

Status	Meaning
400	No wallet had enough balance to prepare the swap at all. Payload includes insufficientWallets, insufficientTokenWallets, and stats.
404	One or more wallets not owned. Response includes missing.

Example

curl -X POST "$BASE_URL/trading/swap" \
  -H "Authorization: Bearer $ACCESS" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sTokenAddress": "…",
    "aWalletAddresses": ["wallet1", "wallet2"],
    "eSwapType": "BUY",
    "eSwapValueType": "EXACT",
    "nValue": 0.1
  }'