Sell On Secondary Market

Create a sell order on the secondary market for tokens owned by a user.

Endpoint

POST /v2/users/secondary-markets/users/{user_id}/tokens/{token_id}/sell

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
user_id	string	Yes	The unique identifier of the user selling the tokens
token_id	string	Yes	The unique identifier of the token to sell

Request Body

{
    "quantity": 10,
    "price_id": "6913307ec95e268b239b2d8b",
    "price_amount": 12
}

Parameters

Parameter	Type	Required	Description
quantity	integer	Yes	Number of tokens to sell
price_id	string	Yes	Currency token ID
price_amount	number	Yes	Price amount per token

Response

Returns a transaction ID for async processing. A user transaction row is created with type = 3 (SellOnSecondaryMarket), environment = 2 (SecondaryMarketEnvironment), and status = 1 (Started).

Success Response (200 OK)

{
    "transaction_id": "6913872755654191dede37da"
}

Response Fields

Field	Type	Description
transaction_id	string	User transaction ID. Poll it via Get User Transactions (filter by types=3) until status reaches 3 (Done) or 4 (Error). The listing becomes orderbook-visible only after Done.

Example

Request

curl -X POST "\{\{baseUrl\}\}/v2/users/secondary-markets/users/680c02896d91ca0145cfeb81/tokens/68ae06cfcccf4e8fc19362d1/sell" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}" \
  -d '{
    "quantity": 10,
    "price_id": "6913307ec95e268b239b2d8b",
    "price_amount": 12
  }'

Response

{
    "transaction_id": "6913872755654191dede37da"
}

Note: Poll Get User Transactions for the returned transaction_id to track order completion. The token quantity is held off-balance until the listing settles on-chain.

Error Responses

400 Bad Request

{
    "error": "Invalid parameters",
    "details": "Quantity must be greater than 0"
}

401 Unauthorized

{
    "error": "Authentication required"
}

403 Forbidden

{
    "error": "Access denied",
    "details": "Insufficient permissions to sell tokens"
}

404 Not Found

{
    "error": "Resource not found",
    "details": "User or token not found"
}

422 Unprocessable Entity

{
    "error": "Insufficient token balance",
    "details": "User does not have enough tokens to sell"
}

500 Internal Server Error

{
    "error": "Internal server error"
}

Important Notes

• Async Processing: Sell order is created asynchronously; use transaction_id to poll status
• Token Ownership: User must own the tokens they want to sell
• Price: price_id is the currency token ID, price_amount is the price per token
• Polling: Get User Transactions, filter by types=3 (SellOnSecondaryMarket)
• Transaction storage: Secondary-market settlements live in the secondary_market_transactions collection. The user transaction (type=3) is the orchestration record exposed via this API