Agent SAPI API Reference
Complete API reference for all C2C Agent SAPI endpoints used by the P2P Skill (Phase 3).
All endpoints require authentication (API Key + HMAC SHA256 signature).
See authentication.md for signing details.
Base URL: https://api.binance.com
Common Headers:
X-MBX-APIKEY: {your_api_key}
User-Agent: binance-wallet/1.0.0 (Skill)Common Response Wrapper:
{
"code": "000000",
"message": null,
"data": { ... },
"success": true
}Paginated Response Wrapper:
{
"code": "000000",
"data": [ ... ],
"total": 100,
"success": true
}1. Order Match APIs
1.1 Get Order Detail
Get detailed information for a specific order.
POST /sapi/v1/c2c/agent/orderMatch/getUserOrderDetailRequest Body (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
| orderNumber | String | Yes | Order number to query |
Response (AgentOrderDetailResp):
| Field | Type | Description |
|---|---|---|
| orderNumber | String | Order number |
| advOrderNumber | String | Advertisement order number |
| tradeType | String | BUY / SELL |
| orderStatus | Integer | 1=Unpaid, 2=Paid, 3=Appealing, 4=Completed, 6=Cancelled, 7=CancelledBySystem |
| asset | String | Crypto asset (e.g. USDT) |
| amount | BigDecimal | Crypto amount |
| price | BigDecimal | Unit price |
| totalPrice | BigDecimal | Total fiat amount |
| fiatUnit | String | Fiat currency code |
| fiatSymbol | String | Fiat symbol (e.g. ¥) |
| buyerNickname | String | Buyer nickname (not masked) |
| sellerNickname | String | Seller nickname (not masked) |
| createTime | Date | Order creation time |
| notifyPayTime | Date | Buyer marked paid time |
| confirmPayTime | Date | Seller confirmed time |
| cancelTime | Date | Order cancel time |
| notifyPayEndTime | Date | Payment deadline |
| confirmPayEndTime | Date | Release deadline |
| isComplaintAllowed | Boolean | Whether complaint is allowed |
| complaintStatus | Integer | Complaint status |
| commissionRate | BigDecimal | Maker commission rate |
| commission | BigDecimal | Maker commission amount |
| takerCommissionRate | BigDecimal | Taker commission rate |
| takerCommission | BigDecimal | Taker commission amount |
| takerAmount | BigDecimal | Taker net amount |
Example:
curl -X POST "https://api.binance.com/sapi/v1/c2c/agent/orderMatch/getUserOrderDetail?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
-H "X-MBX-APIKEY: ${API_KEY}" \
-H "User-Agent: binance-wallet/1.0.0 (Skill)" \
-H "Content-Type: application/json" \
-d '{"orderNumber": "20260315123456789"}'Note: See
authentication.mdfor the complete Bash signing setup.
1.2 List Orders
List orders with rich filters and pagination.
POST /sapi/v1/c2c/agent/orderMatch/listOrdersRequest Body (JSON):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| advNo | String | No | — | Filter by advertisement number |
| asset | String | No | — | Filter by crypto asset |
| orderStatus | Integer | No | — | Filter by single status |
| tradeType | String | No | — | 0=BUY, 1=SELL |
| payType | Integer | No | — | Filter by payment method type |
| orderStatusList | List<Integer> | No | — | Filter by multiple statuses |
| startDate | Long | No | — | Start timestamp (ms) |
| endDate | Long | No | — | End timestamp (ms) |
| page | Integer | No | 1 | Page number |
| rows | Integer | No | 20 | Page size (max 20) |
Response (Paginated List of AgentOrderListResp):
| Field | Type | Description |
|---|---|---|
| orderNumber | String | Order number |
| advNo | String | Advertisement number |
| tradeType | String | Trade type |
| asset | String | Crypto asset |
| fiat | String | Fiat currency |
| fiatSymbol | String | Fiat symbol |
| amount | String | Crypto amount |
| totalPrice | String | Total fiat amount |
| orderStatus | Integer | Status code |
| createTime | Date | Creation time |
| confirmPayEndTime | Date | Release deadline |
| notifyPayEndTime | Date | Payment deadline |
| buyerNickname | String | Buyer nickname |
| sellerNickname | String | Seller nickname |
| commissionRate | BigDecimal | Maker commission rate |
| commission | BigDecimal | Maker commission |
| takerCommissionRate | BigDecimal | Taker commission rate |
| takerCommission | BigDecimal | Taker commission |
| takerAmount | BigDecimal | Taker net amount |
1.3 List User Order History
List historical orders with pagination.
GET /sapi/v1/c2c/agent/orderMatch/listUserOrderHistoryQuery Parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| startTimestamp | Long | No | 30 days ago | Start timestamp (ms) |
| endTimestamp | Long | No | now | End timestamp (ms) |
| tradeType | String | No | — | BUY / SELL |
| page | Integer | No | 1 | Page number (min 1) |
| rows | Integer | No | 100 | Page size (min 1, max 100) |
Response (Paginated List of AgentOrderHistoryResp):
| Field | Type | Description |
|---|---|---|
| orderNumber | String | Order number |
| advNo | String | Advertisement number |
| tradeType | String | Trade type |
| asset | String | Crypto asset |
| fiat | String | Fiat currency |
| fiatSymbol | String | Fiat symbol |
| amount | String | Crypto amount |
| totalPrice | String | Total fiat amount |
| unitPrice | BigDecimal | Unit price |
| orderStatus | String | Status name (e.g. COMPLETED) |
| createTime | Date | Creation time |
| commission | BigDecimal | Commission |
| takerCommissionRate | BigDecimal | Taker commission rate |
| takerCommission | BigDecimal | Taker commission |
| takerAmount | BigDecimal | Taker net amount |
| counterPartNickName | String | Counterparty nickname (not masked) |
| payMethodName | String | Payment method name |
| advertisementRole | String | MAKER / TAKER |
2. Complaint APIs
2.1 Query Complaints
Query complaint/appeal records with filters and pagination.
POST /sapi/v1/c2c/agent/complaint/query-complaintsRequest Body (JSON):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| roleIdentity | String | No | — | COMPLAINANT or RESPONDENT |
| orderNoList | List<String> | No | — | Filter by order numbers |
| complaintStatusList | List<Integer> | No | — | Filter by complaint statuses |
| orderStatusListWhenInitiate | List<Integer> | No | — | Filter by order status at complaint time |
| startTime | Date | No | 90 days ago | Query start time |
| endTime | Date | No | now | Query end time |
| page | Integer | No | 1 | Page number |
| rows | Integer | No | 20 | Page size |
Response (Paginated List of AgentComplaintQueryResp):
| Field | Type | Description |
|---|---|---|
| orderNo | String | Order number |
| complaintNo | Long | Complaint number |
| complaintStatus | Integer | Complaint status |
| orderStatusWhenInitiate | Integer | Order status when complaint was filed |
| complaintCreateTime | Date | Complaint creation time |
| reason | String | Complaint reason |
| roleIdentity | String | COMPLAINANT / RESPONDENT |
| orderFiat | String | Order fiat currency |
| orderAsset | String | Order crypto asset |
| orderAmount | BigDecimal | Order amount |
| orderAmountInUsdt | BigDecimal | Order amount in USDT |
| disputeAmount | BigDecimal | Dispute amount |
3. Ads APIs
3.1 Get Ad Detail By Number
POST /sapi/v1/c2c/agent/ads/getDetailByNo?advNo={advNo}Query Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
| advNo | String | Yes | Advertisement number |
Note: This endpoint only returns ads owned by the authenticated user. Querying another user's ad will return error
-1002.
Response (AgentAdDetailResp):
| Field | Type | Description |
|---|---|---|
| advNo | String | Advertisement number |
| classify | String | mass / profession / block / cash |
| tradeType | String | BUY / SELL |
| asset | String | Crypto asset |
| fiatUnit | String | Fiat currency code |
| advStatus | Integer | 1=Online, 3=Offline, 4=Closed |
| priceType | Integer | 1=Fixed, 2=Floating |
| priceFloatingRatio | BigDecimal | Floating ratio % |
| price | BigDecimal | Unit price |
| initAmount | BigDecimal | Initial amount |
| surplusAmount | BigDecimal | Remaining amount |
| tradableQuantity | BigDecimal | Tradable quantity |
| maxSingleTransAmount | BigDecimal | Max fiat per order |
| minSingleTransAmount | BigDecimal | Min fiat per order |
| payTimeLimit | Integer | Payment time limit (min) |
| remarks | String | Remarks |
| autoReplyMsg | String | Auto reply message |
| createTime | Date | Creation time |
| tradeMethods | List<AgentTradeMethodResp> | Payment methods |
| commissionRate | BigDecimal | Commission rate |
| buyerKycLimit | Integer | Buyer KYC required |
| buyerRegDaysLimit | Integer | Buyer min reg days |
| buyerBtcPositionLimit | BigDecimal | Buyer min BTC |
| takerAdditionalKycRequired | Integer | Extra verification |
AgentTradeMethodResp:
| Field | Type | Description |
|---|---|---|
| identifier | String | Method identifier (e.g. ALIPAY) |
| tradeMethodName | String | Display name |
| iconUrlColor | String | Icon URL |
3.2 List Ads With Pagination
List current user's own advertisements.
POST /sapi/v1/c2c/agent/ads/listWithPaginationRequest Body (JSON):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| page | Integer | No | 1 | Page number |
| rows | Integer | No | 20 | Page size |
Response: Paginated list of AgentAdDetailResp (same schema as 3.1).
3.3 Search Ads
Search market ads with rich filters.
POST /sapi/v1/c2c/agent/ads/searchRequest Body (JSON):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| publisherType | String | No | — | "user" or "merchant" |
| fiat | String | Yes | — | Fiat currency |
| asset | String | Yes | — | Crypto asset |
| tradeType | String | Yes | — | BUY / SELL |
| payTypes | List<String> | No | — | Payment method filters |
| transAmount | BigDecimal | No | — | Transaction amount filter |
| countries | List<String> | No | — | Country filters |
| classifies | List<String> | No | auto | Ad classifies filter |
| page | Integer | No | 1 | Page number |
| rows | Integer | No | 20 | Page size |
Response (Paginated List of AgentAdSearchResp):
| Field | Type | Description |
|---|---|---|
| adv | AgentAdDetailResp | Ad detail (see 3.1) |
| advertiser | AgentAdvertiserResp | Advertiser info |
AgentAdvertiserResp:
| Field | Type | Description |
|---|---|---|
| userNo | String | User number |
| nickName | String | Nickname (not masked) |
| orderCount | Integer | Total order count |
| monthOrderCount | Integer | 30-day orders |
| monthFinishRate | BigDecimal | 30-day completion rate |
| advConfirmTime | Integer | Avg release time (seconds) |
| userType | String | user / merchant |
| tagIconUrls | List<String> | Tag icon URLs |
3.4 Get Reference Price
Get market reference prices for pricing decisions.
POST /sapi/v1/c2c/agent/ads/getReferencePriceRequest Body (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
| assets | List<String> | No | Crypto assets (max 3), e.g. ["BTC","ETH","USDT"] |
| fiatCurrency | String | Yes | Fiat currency |
| tradeType | String | Yes | BUY or SELL |
| payType | String | No | Payment method filter |
Response (List of AgentAdReferencePriceResp):
| Field | Type | Description |
|---|---|---|
| asset | String | Crypto asset |
| currency | String | Fiat currency |
| currencyScale | Integer | Fiat decimal scale |
| currencySymbol | String | Fiat symbol |
| referencePrice | BigDecimal | Reference exchange rate |
| assetScale | Integer | Asset decimal scale |
| priceScale | Integer | Price decimal scale |
3.5 Get Available Ads Category
Get ad categories the current user can publish.
GET /sapi/v1/c2c/agent/ads/getAvailableAdsCategoryNo request body.
Response (AgentAdsCategoryResp):
| Field | Type | Description |
|---|---|---|
| advClassifies | List<String> | Available classifies: mass, profession, block, cash |
3.6 Get User Payment Methods
Get current user's configured payment methods (agent-safe: no account details).
GET /sapi/v1/c2c/agent/ads/getPayMethodByUserIdNo request body.
Response (List of AgentPayMethodResp):
| Field | Type | Description |
|---|---|---|
| payId | Long | Payment method ID (needed for SELL ads) |
| identifier | String | Method identifier (e.g. ALIPAY) |
| tradeMethodName | String | Display name |
Note: For SELL ads, use
payIdin tradeMethods. For BUY ads, useidentifierfrom system trade methods.
3.7 List All System Trade Methods
List all available trade methods in the system.
POST /sapi/v1/c2c/agent/ads/listAllTradeMethodsNo request body.
Response (List of TradeMethodBaseInfoVO):
| Field | Type | Description |
|---|---|---|
| identifier | String | Trade method identifier |
| tradeMethodName | String | Display name |
| (other fields) | — | Additional method info |
3.8 Post Ad (Write Operation)
Publish a new advertisement. Requires merchant permission.
POST /sapi/v1/c2c/agent/ads/postRequest Body (JSON):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| classify | String | Yes | "mass" | Ad category |
| tradeType | String | Yes | — | 0=BUY, 1=SELL |
| asset | String | Yes | — | Crypto asset |
| fiatUnit | String | Yes | — | Fiat currency |
| priceType | Integer | Yes | — | 1=Fixed, 2=Floating |
| priceFloatingRatio | BigDecimal | Conditional | — | Required if priceType=2 |
| rateFloatingRatio | BigDecimal | No | — | Exchange rate floating |
| price | BigDecimal | Conditional | — | Required if priceType=1 |
| initAmount | BigDecimal | Yes | — | Total crypto amount |
| maxSingleTransAmount | BigDecimal | Yes | — | Max fiat per order |
| minSingleTransAmount | BigDecimal | Yes | — | Min fiat per order |
| buyerKycLimit | Integer | Yes | — | 0=No, 1=Yes |
| buyerRegDaysLimit | Integer | No | — | Min buyer reg days |
| buyerBtcPositionLimit | BigDecimal | No | — | Min buyer BTC |
| remarks | String | No | — | Max 1000 chars |
| autoReplyMsg | String | No | — | Max 1000 chars |
| onlineNow | Boolean | No | — | Go online immediately |
| payTimeLimit | Integer | No | — | Payment time limit (min) |
| tradeMethods | List<TradeMethod> | Yes | — | Payment methods |
| takerAdditionalKycRequired | Integer | No | — | 0=No, 1=Yes |
| launchCountry | List<String> | No | — | Target countries |
TradeMethod object:
| Field | Type | Description |
|---|---|---|
| payId | Long | User's payment method ID (for SELL ads) |
| payType | String | Payment type |
| identifier | String | Trade method identifier (for BUY ads) |
Response: CommonRet<String> where data is the new ad number (advNo).
3.9 Update Ad (Write Operation)
Update an existing advertisement. Requires merchant permission.
Important — full-object update: The downstream service validates the complete ad object, not just the changed fields. Sending only
advNo+ one field (e.g.price) will result in error-9000. The recommended workflow is:
- Call
getDetailByNo?advNo={advNo}to fetch the current ad.- Merge your changes into the full response object.
- Submit the merged object to this endpoint.
POST /sapi/v1/c2c/agent/ads/updateRequest Body (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
| advNo | String | Yes | Ad number to update |
| tradeType | String | No | 0=BUY, 1=SELL |
| asset | String | No | Crypto asset |
| fiatUnit | String | No | Fiat currency |
| priceType | Integer | No | 1=Fixed, 2=Floating |
| priceFloatingRatio | BigDecimal | No | Floating ratio |
| rateFloatingRatio | BigDecimal | No | Rate floating |
| price | BigDecimal | No | Fixed price |
| initAmount | BigDecimal | No | Total amount |
| maxSingleTransAmount | BigDecimal | No | Max fiat per order |
| minSingleTransAmount | BigDecimal | No | Min fiat per order |
| buyerKycLimit | Integer | No | 0=No, 1=Yes |
| buyerRegDaysLimit | Integer | No | Min reg days |
| buyerBtcPositionLimit | BigDecimal | No | Min BTC |
| remarks | String | No | Remarks |
| autoReplyMsg | String | No | Auto reply |
| payTimeLimit | Integer | No | Payment time limit |
| tradeMethods | List<TradeMethod> | No | Payment methods |
| advStatus | Integer | No | 1=Online, 3=Offline, 4=Closed |
| takerAdditionalKycRequired | Integer | No | 0=No, 1=Yes |
| launchCountry | List<String> | No | Countries |
Response: CommonRet<Boolean> — true if update succeeded.
3.10 Update Ad Status (Write Operation)
Batch update advertisement status (online/offline/close).
POST /sapi/v1/c2c/agent/ads/updateStatusRequest Body (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
| advNos | List<String> | Yes | Ad numbers to update (min 1) |
| advStatus | Integer | Yes | 1=Online, 3=Offline, 4=Closed |
Response (AgentAdUpdateStatusResp):
| Field | Type | Description |
|---|---|---|
| status | Boolean | Overall success/failure |
| failList | List<StatusUpdateResult> | Failed items (if any) |
StatusUpdateResult:
| Field | Type | Description |
|---|---|---|
| advNo | String | Failed ad number |
| errorCode | String | Error code |
| errorMessage | String | Error description |
4. Merchant APIs
4.1 Get Merchant Ad Details
Get merchant public profile with buy/sell ad listings.
GET /sapi/v1/c2c/agent/merchant/getAdDetails?merchantNo={merchantNo}Query Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
| merchantNo | String | Yes | Merchant number |
Response (AgentMerchantAdsDetailResp):
| Field | Type | Description |
|---|---|---|
| merchant | AgentMerchantDetailResp | Merchant profile |
| buyList | List<AgentAdDetailResp> | Buy advertisements |
| sellList | List<AgentAdDetailResp> | Sell advertisements |
AgentMerchantDetailResp:
| Field | Type | Description |
|---|---|---|
| merchantNo | String | Merchant number |
| userType | String | user / merchant |
| nickName | String | Nickname (not masked) |
| orderCount | Integer | Total order count |
| monthOrderCount | Integer | 30-day orders |
| monthFinishRate | BigDecimal | 30-day completion rate |
| advConfirmTime | Integer | Avg release time (s) |
| onlineStatus | String | 0=Offline, 1=Online |
| registerDays | Integer | Registration days |
| firstOrderDays | Integer | Days since first order |
| avgReleaseTimeOfLatest30day | Double | 30-day avg release (s) |
| avgPayTimeOfLatest30day | Double | 30-day avg payment (s) |
| completedOrderNumOfLatest30day | Long | 30-day completed orders |
5. Support APIs
5.1 List Digital Currencies
POST /sapi/v1/c2c/agent/digitalCurrency/listNo request body.
Response: List<DigitalCurrencyResponse> — all supported digital currencies.
5.2 List Fiat Currencies
POST /sapi/v1/c2c/agent/fiatCurrency/listNo request body.
Response: List<FiatCurrencyResponse> — all supported fiat currencies.
Authentication Notes
All Agent SAPI endpoints share the same authentication mechanism:
- All requests require
timestampandsignaturequery parameters - SAPI signing: DO NOT sort parameters — keep insertion order
- Required headers:
X-MBX-APIKEY+User-Agent - See
authentication.mdfor complete signing process
Privacy & Security
All Agent SAPI responses are pre-filtered at the DTO level:
- Excluded: real names, phone numbers, emails, bank accounts, payment details, KYC info
- Included: nicknames (not masked), order/ad data, trade statistics
- The Agent field filter (
AgentFieldFilter) handles any runtime masking needed
6. File Upload (AgentFileUploadController)
Base path: /sapi/v1/c2c/agent/file-upload
6.1 Get S3 Presigned URL
GET /sapi/v1/c2c/agent/file-upload/get-s3-presigned-urlGet a presigned S3 URL for uploading complaint evidence files. The URL is valid for 5 minutes.
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| fileName | String | Yes | File name with extension, e.g. proof.jpg |
| scenario | String | No | Upload scenario. Default: complaint. Agent only supports complaint. |
Response: S3FileUrlInfo
| Field | Type | Description |
|---|---|---|
| uploadUrl | String | S3 presigned upload URL (PUT to this URL with file binary) |
| filePath | String | Final file path in S3 (use this in submit-evidence fileUrls) |
Supported file types (complaint scenario):
txt, doc, xls, docx, xlsx, jpg, jpeg, png, pdf, mp3, mp4, avi, rm, rmvb, mov, wmv
Upload flow:
- Call this endpoint to get
uploadUrlandfilePath PUTthe file binary touploadUrl(must complete within 5 minutes)- Use
filePathin thesubmit-evidencerequest
7. Complaint Operations (AgentComplaintController — Extended)
These endpoints extend the existing complaint controller (Section 2).
7.1 Submit Appeal Evidence
POST /sapi/v1/c2c/agent/complaint/submit-evidenceSubmit supplementary evidence for an existing complaint/appeal.
Request Body: AgentComplaintSupplementReq
| Field | Type | Required | Description |
|---|---|---|---|
| orderNo | String | Yes | Order number |
| description | String | Yes | Evidence description (1-500 chars) |
| fileUrls | List<String> | No | List of S3 file paths from presigned upload |
Response: Boolean — true if evidence submitted successfully.
Error cases:
- Order not found / not in appeal → error response
- No active complaint for order → error response
- File URLs not from valid S3 upload → may fail validation
7.2 Get Complaint Flows (Timeline)
POST /sapi/v1/c2c/agent/complaint/get-complaint-flowsGet the chronological timeline of a complaint process, including all actions, evidence submissions, and CS reviews.
Request Body: AgentComplaintFlowQueryReq
| Field | Type | Required | Description |
|---|---|---|---|
| orderNo | String | Yes | Order number |
| complaintNo | Long | No | Specific complaint number (optional; narrows to specific complaint) |
Response: List<AgentComplaintFlowResp>
| Field | Type | Description |
|---|---|---|
| complaintNo | Long | Complaint number |
| orderNo | String | Order number |
| infoType | Integer | Flow info type (1=Initiated, 2=Evidence, 3=CS Note, 4=Resolution) |
| description | String | Flow entry description |
| fileUrls | List<String> | Evidence file URLs (CDN-assembled, directly accessible) |
| creatorNickName | String | Creator nickname |
| operatorName | String | Operator name (CS agent if applicable) |
| remark | String | Remark (plain text) |
| remarkHtml | String | Remark (HTML version; takes precedence over remark when available) |
| createTime | Date | Flow entry creation time |
| source | String | Flow info source |
7.3 Cancel Complaint
POST /sapi/v1/c2c/agent/complaint/cancel-complaintCancel (withdraw) an existing complaint/appeal for an order. This is an irreversible action.
Request Body: AgentComplaintCancelReq
| Field | Type | Required | Description |
|---|---|---|---|
| orderNo | String | Yes | Order number of the complaint to cancel |
Response: Boolean — true if the complaint was successfully cancelled.
Error cases:
- Order not found → error response
- No active complaint for order → error response
- Complaint already resolved/closed → error response
- User not the complaint initiator → error response
Important: The agent MUST confirm with the user before calling this endpoint, as cancelling an appeal is irreversible and the user forfeits their dispute rights.
7.4 Get Complaint Reasons
POST /sapi/v1/c2c/agent/complaint/get-complaint-reasonsGet available complaint/appeal reasons for a given order. Returns localized reason descriptions.
Request Body: AgentComplaintCancelReq (reused — only needs orderNo)
| Field | Type | Required | Description |
|---|---|---|---|
| orderNo | String | Yes | Order number to get complaint reasons for |
Response: List<AgentComplaintReasonResp>
| Field | Type | Description |
|---|---|---|
| reasonCode | Integer | Reason code identifier |
| reasonDesc | String | Localized reason description |
Error cases:
- Order not found → error response
- Order not in a state where complaints are applicable → error response