Create/Update Ad
Create a new ad or update an existing ad.
HTTP Request
-
POST
/api/v3/fiat/merchant/ads/save_or_update -
Note: Request parameters should be passed as key=value&key=value in the URL query string. JSON body is not supported.
Required Permission: P2P Deal Ad
Request Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| advNo | string | no | Ad unique identifier (required when updating) |
| payTimeLimit | integer | yes | Payment time limit (minutes) |
| initQuantity | BigDecimal | yes | Initial tradable quantity |
| supplyQuantity | BigDecimal | no | When updating an ad, this parameter specifies the number of ads to be added. The value cannot be negative. |
| reduceQuantity | BigDecimal | no | When updating an ad, this parameter specifies the number of ads to be reduced. |
| price | BigDecimal | yes | Price per unit |
| coinId | string | yes | Crypto coin ID (e.g., BTC, ETH) |
| countryCode | string | no | Country code |
| side | string | yes | Trade direction: BUY / SELL |
| advStatus | string | no | If provided during update, also updates ad status. See enum values |
| fiatUnit | string | yes | Fiat currency type (e.g., USD, EUR) |
| payMethod | string | yes | User payment account ID(s), comma-separated |
| autoReplyMsg | string | no | Auto-reply message |
| tradeTerms | string | no | Trade terms |
| minSingleTransAmount | BigDecimal | yes | Minimum single trade amount |
| maxSingleTransAmount | BigDecimal | yes | Maximum single trade amount |
| kycLevel | string | no | Required KYC level for counterparty |
| userAllTradeCountMin | integer | yes | Minimum completed trades required |
| userAllTradeCountMax | integer | yes | Maximum trades limit |
| maxPayLimit | integer | no | Max orders per user on this ad |
| buyerRegDaysLimit | integer | no | Minimum buyer registration days |
| priceType | integer | no | Price type: 0=fixed (default), 1=floating |
| priceRatio | BigDecimal | conditional | Floating ratio, required when priceType=1. Range depends on fiat currency config |
| overVerify | string | no | Only applicable to SELL ads when the advertiser is a verified merchant and additional verification is enabled for the fiat currency. Up to 3 types can be selected. Format: {"types":[1,3]} or {"types":[1,6],"otherText":"Please provide xxx proof"}Types: - 1 = ID Card (ID_CARD) - 2 = Passport (PASSPORT) - 3 = Selfie (SELFIE) - 4 = Proof of Address (UTILITY_BILL) - 5 = Billing Statement (BILLING) - 6 = Other (OTHER) otherText: Required when types includes 6; otherwise, omit this field. Note: The JSON string must be fully URL-encoded when passed as a query parameter. Otherwise, the gateway may return a 400 error. Example: overVerify=%7B%22types%22%3A%5B1%2C3%5D%7D |
| supportKycCountry | string | no | Restrict taker KYC country list, comma-separated e.g. US,GB,JP, max 10 |
| merchantTradeEnable | boolean | no | Allow other merchants to place orders, default true. Only certified/preferred/gold merchants can set to false |
| onlyTradeKybUser | boolean | no | Only KYB enterprise users can place orders, only KYB merchants can set to true |
| paymethodIds | string | conditional | Payment method type ID list for BUY ads (comma-separated e.g. "1,2"), required for BUY ads instead of payMethod. Get type IDs from /api/payment/user response data[].payMethod. Mutually exclusive with payMethod: SELL ads use payMethod (account instance ID), BUY ads use paymethodIds (method type ID) |
| display | integer | no | Advertisement visibility. - 1: Public (default) - 2: Private advertisement |
| adsType | integer | no | Ad Type: 1: Regular Ad (default), 2: Whitelist Zone Ad. The adDisplayAreaType and Whitelist Zone payment method-related fields only take effect when adsType is set to 2. |
| adDisplayAreaType | integer | no | Advertisement display area. - 1: Display in both the General Zone and Whitelist Zone (default) - 2: Display in the Whitelist Zone only |
| securityOrderPaymethodIds | string | no | Payment method type IDs for whitelist zone advertisements (comma-separated). Used for BUY advertisements when adDisplayAreaType=2 |
| securityOrderPaymentInfo | string | no | Payment account IDs for whitelist zone advertisements (comma-separated). Used for SELL advertisements when adDisplayAreaType=2 |
Response Parameters
| Name | Type | Description |
|---|---|---|
| code | integer | 0 indicates success |
| msg | string | Result description |
| data | string | Ad number (advNo) |
Response
{
"code": 0,
"msg": "success",
"data": "a1375750128856004608"
}