Buy On Primary Market
Buys quantity tokens from the issuer at the token's current price. The buy is asynchronous: it records a user transaction (type = 1, purchase on primary market) and answers with its transaction_id. Poll Get User Transaction until status is 3 (done) or 4 (error); the user owns the tokens only after 3. For a platform token the purchase also appears at once in List User Purchases with status = 1 (pending).
wallet_id is required and names the buyer's wallet the tokens are bought into. It must be this user's wallet and sit on the token's chain; it is never derived, because a buyer may hold several wallets there. That wallet also signs the on-chain purchase: the payment currency is pulled from it and it pays the gas, so fund the wallet you name. Show the cost first with Quote Primary Market Purchase.
The token must be listed. For a platform token the quantity must fit in the remaining supply (listed_supply − sold_supply + purchased_supply), and the user's holding plus quantity must not exceed the token's per-user cap (metric.max_purchase_quantity, 0 = no cap; see Get Purchase Quantity).
Required permission: purchase:create
Request
POST /v2/users/{user_id}/purchases/tokens/{token_id}/buy-on-primary-market
Parameters
| Name | Type | In | Description |
|---|---|---|---|
user_id | string | path | Required. Buyer's user ID |
token_id | string | path | Required. Token ID |
Headers
| Name | Description |
|---|---|
Authorization | Required. Bearer <access_token> |
Content-Type | Required. application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
quantity | integer | Yes | Whole tokens to buy, at least 1 |
wallet_id | string | Yes | Buyer's wallet (wallets._id) the tokens are bought into and the purchase is signed from. Must belong to the user and sit on the token's chain |
Example
curl --request POST \
--url '{{baseUrl}}/v2/users/680c02896d91ca0145cfeb81/purchases/tokens/68ae06cfcccf4e8fc19362d1/buy-on-primary-market' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"quantity": 10,
"wallet_id": "6a89b68e0c46ca4c941271aa"
}'
Response
{
"transaction_id": "6913872755654191dede37da"
}
Response Fields
| Field | Type | Description |
|---|---|---|
transaction_id | string | User transaction that carries the purchase. Poll it with Get User Transaction |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | 10015 | Validation failed (quantity, wallet_id) — see details |
| 400 | 10016 | user_id, token_id or wallet_id is not a valid 24-character hex id |
| 400 | 10001 | Token not found (domain 5) |
| 400 | 10011 | Token is not listed (domain 5, token is not active) |
| 400 | 10001 | User not found (domain 1) |
| 400 | 10015 | Domain 1: wallet does not belong to this user on this network — the wallet does not exist, is not this user's, or is on another chain |
| 400 | 10024 | Not enough supply left for this quantity (domain 5) |
| 400 | 10025 | The buy would take the user's holding above the per-user cap (domain 5) |
| 500 | 10000 | Unexpected server-side failure |
A failure after the buy was accepted (for example a wallet without enough native balance for gas) does not become an HTTP error: the transaction ends in status = 4 with the reason in its error field.
See Errors for the error format and common codes.