Index of every page on this site: llms.txt
All skills
binance avatar
by binancebinance/binance-skills-hub1.2k stars
281
Run it yourself

Binance P2P trading assistant for natural-language queries about P2P/C2C market ads, the user's own P2P order history, order detail & appeal tracking, and advertisement publish & management. Use when the user asks about P2P prices, searching/choosing ads, comparing payment methods, reviewing P2P order history, checking order detail/appeal status, querying complaints, publishing/updating/managing P2P advertisements, or viewing merchant profiles. Do NOT use for spot/futures prices, exchange trading, deposits/withdrawals, on-chain transfers, or anything unrelated to P2P/C2C.

Use this Skill: https://skilld.dev/gh/binance/binance-skills-hub/p2p

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesagent-sapi-api.md

≈6.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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/getUserOrderDetail

Request 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.md for the complete Bash signing setup.


1.2 List Orders

List orders with rich filters and pagination.

POST /sapi/v1/c2c/agent/orderMatch/listOrders

Request 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/listUserOrderHistory

Query 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-complaints

Request 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/listWithPagination

Request 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/search

Request 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/getReferencePrice

Request 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/getAvailableAdsCategory

No 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/getPayMethodByUserId

No 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 payId in tradeMethods. For BUY ads, use identifier from system trade methods.


3.7 List All System Trade Methods

List all available trade methods in the system.

POST /sapi/v1/c2c/agent/ads/listAllTradeMethods

No 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/post

Request 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:

  1. Call getDetailByNo?advNo={advNo} to fetch the current ad.
  2. Merge your changes into the full response object.
  3. Submit the merged object to this endpoint.
POST /sapi/v1/c2c/agent/ads/update

Request 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/updateStatus

Request 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/list

No request body.

Response: List<DigitalCurrencyResponse> — all supported digital currencies.


5.2 List Fiat Currencies

POST /sapi/v1/c2c/agent/fiatCurrency/list

No request body.

Response: List<FiatCurrencyResponse> — all supported fiat currencies.


Authentication Notes

All Agent SAPI endpoints share the same authentication mechanism:

  1. All requests require timestamp and signature query parameters
  2. SAPI signing: DO NOT sort parameters — keep insertion order
  3. Required headers: X-MBX-APIKEY + User-Agent
  4. See authentication.md for 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-url

Get 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:

  1. Call this endpoint to get uploadUrl and filePath
  2. PUT the file binary to uploadUrl (must complete within 5 minutes)
  3. Use filePath in the submit-evidence request

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-evidence

Submit 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-flows

Get 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-complaint

Cancel (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-reasons

Get 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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill is a Binance P2P trading assistant that allows users to query market prices, manage advertisements, and track orders or appeals. It incorporates several security best practices, including mandatory user confirmation for any actions that modify data, privacy-preserving data masking for counterparty information, and clear instructions for the secure management of API credentials.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: MEDIUM · 1 issue

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 7d1b1f7. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 7 months ago

README badge

README badge for binance/binance-skills-hub/p2p