POST /holders/initialize

Create a pending holders order.

Reserves an order and returns paymentAddress + nRequiredSol. On payment, a worker fans out buys across N fresh wallets to create holders. Fixed tiers only.

Use case

Boost holder count on a newly-launched token — pick a tier, pay once, worker spreads small buys across N wallets.

Body

Field	Type	Required	Description
sTokenAddress	string	yes	Token mint.
sPoolId	string	yes	Pool id for the mint.
ePoolChosen	enum	yes	RAYDIUM, METEORA, MOONIT, MOONSHOT, PUMPFUN, PUMPSWAP, LAUNCHLAB, HEAVEN, DBC.
nHoldersCount	integer	yes	Must match one of the tiers (500, 1000, 2500, 5000, 10000, 20000).

Singleton rule

Each user can have at most one order awaiting payment at a time. 409 if another is pending:

{
  "message": "this user already has a pending Holders order — complete or cancel it before initializing another",
  "pendingHoldersId": "66b4…"
}

Response 202

{
  "holdersId": "66b4…",
  "status": "PENDING_PAYMENT",
  "paymentAddress": "…",
  "nRequiredSol": 1.5,
  "nHoldersCount": 500,
  "sTokenAddress": "…",
  "sPoolId": "…",
  "ePoolChosen": "RAYDIUM"
}

Errors

Status	Meaning
400	Invalid inputs or nHoldersCount not in tier set.
409	User already has a pending order.

Example

curl -X POST "$BASE_URL/holders/initialize" \
  -H "Authorization: Bearer $ACCESS" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sTokenAddress": "…",
    "sPoolId": "…",
    "ePoolChosen": "RAYDIUM",
    "nHoldersCount": 500
  }'