Buy On Primary Market

Purchase tokens directly from the primary market at the initial offering price.

Endpoint

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

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 making the purchase
token_id	string	Yes	The unique identifier of the token to purchase

Request Body

{
    "quantity": 10
}

Parameters

Parameter	Type	Required	Description
quantity	number	Yes	Number of tokens to purchase

Response

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

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=1) until status reaches 3 (Done) or 4 (Error). The transaction's hash field is populated once the wallet broadcasts on-chain.

Example

Request

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

Response

{
    "transaction_id": "6913872755654191dede37da"
}

Note: Poll Get User Transactions for the returned transaction_id to track purchase completion. Until status is 3 (Done) the user does not yet own the tokens 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 purchase tokens"
}

404 Not Found

{
    "error": "Resource not found",
    "details": "Token not available for primary market purchase"
}

422 Unprocessable Entity

{
    "error": "Purchase not possible",
    "details": "Insufficient token supply available"
}

500 Internal Server Error

{
    "error": "Internal server error"
}

Important Notes

• Async Processing: Purchase is processed asynchronously; use transaction_id to poll status
• Primary Market: Tokens are purchased at the initial offering price set by the issuer
• Supply Check: System verifies sufficient token supply is available
• Transaction Polling: Poll Get User Transactions for the returned transaction_id. Status 3 = Done means the on-chain transfer settled
• Purchase Limits: Subject to token's min_purchase_quantity and max_purchase_quantity
• KYC Requirements: Users may need KYC verification depending on token configuration