Skip to main content

Buy On Secondary Market

Purchase tokens from other users on the secondary market at market-determined prices.

Endpoint​

POST /v2/users/purchases/users/{user_id}/tokens/{token_id}/buy-on-secondary-market

Headers​

HeaderValue
Content-Typeapplication/json
AuthorizationBearer {token}

Path Parameters​

ParameterTypeRequiredDescription
user_idstringYesThe unique identifier of the user making the purchase
token_idstringYesThe unique identifier of the token to purchase

Request Body​

{
    "quantity": 10,
    "deal_id": 13
}

Parameters​

ParameterTypeRequiredDescription
quantityintegerYesNumber of tokens to purchase (min: 1)
deal_idintegerYesThe unique identifier of the specific deal/listing to purchase from

Response​

Returns a transaction ID for async processing. A user transaction row is created with type = 2 (PurchaseOnSecondaryMarket) and status = 1 (Started). The wallet pipeline then transitions it to InProgress → Done (or Error).

Success Response (200 OK)​

{
    "transaction_id": "6913872755654191dede37da"
}

Response Fields​

FieldTypeDescription
transaction_idstringUser transaction ID. Poll it via Get User Transactions (filter by types=2) until status reaches 3 (Done) or 4 (Error).

Example​

Request​

curl -X POST "\{\{baseUrl\}\}/v2/users/purchases/users/680c02896d91ca0145cfeb81/tokens/68ae06cfcccf4e8fc19362d1/buy-on-secondary-market" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer \{\{token\}\}" \
  -d '{
    "quantity": 10,
    "deal_id": 13
  }'

Response​

{
    "transaction_id": "6913872755654191dede37da"
}

Note: Poll Get User Transactions for the returned transaction_id to track purchase completion. The seller's secondary-market deal is debited atomically when the on-chain settlement lands.

Error Responses​

400 Bad Request​

{
    "error": "Invalid parameters",
    "details": "Quantity and deal_id are required"
}

401 Unauthorized​

{
    "error": "Authentication required"
}

403 Forbidden​

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

404 Not Found​

{
    "error": "Deal not found",
    "details": "The specified deal is no longer available"
}

409 Conflict​

{
    "error": "Deal conflict",
    "details": "Another user has already purchased this quantity"
}

422 Unprocessable Entity​

{
    "error": "Purchase not possible",
    "details": "Insufficient quantity available in the deal"
}

500 Internal Server Error​

{
    "error": "Internal server error"
}

Important Notes​

  • Async Processing: Purchase is processed asynchronously; use transaction_id to poll status
  • Transaction Polling: Poll Get User Transactions for completion (status 3 = Done)
  • Market Prices: Prices are set by individual sellers and may vary
  • Deal Availability: Deals can be partially filled or expire
  • Quantity Limits: Cannot purchase more than the available quantity in a deal
  • Environment: This transaction is recorded with environment = 2 (SecondaryMarketEnvironment) — useful when filtering user transactions across markets