P2P Crypto — orders
An order is a trade on an ad. Whoever takes the ad opens the order; the advertiser is the other party. Routes live under /v1/accounts/{accountId}/p2p/orders.
Opening
POST .../p2p/orders with Idempotency-Key, adId, walletId (optional, otherwise the default) and amount (BRL) or cryptoAmount. Before answering 201, CorpX:
- screens both wallets again;
- reserves the ad’s stock;
- holds the buyer’s amount (the hold).
If any step fails, the answer is 4xx and nothing stays locked. On a wallet refusal (422 wallet_not_approved), details.walletOf says whose it is: taker (who opened) or maker (the advertiser). A retry with the same key and the same body returns the same order.
Order price and evidence
The price is locked at opening with a live read of the Binance spot price (GET /api/v3/ticker/price?symbol={ASSET}BRL), the market’s only price source. A spread ad applies its basis points over that spot; an offset ad adds its signed BRL amount (up to 4 decimal places); a fixed ad keeps its fixed price, but Binance is queried all the same to record the market at that moment. The read is uncached: it is that instant.
The unit price keeps 4 decimal places (5.4321) on the order, the evidence and the contract. The order’s BRL amount is what becomes cents, truncated (crypto × price); the fee rounds up to the cent.
The whole HTTP exchange is stored as the order’s price evidence: request (method, URL, headers), response (status, every header, raw body and its sha256), transport (remote IP, TLS session and certificate chain), millisecond timestamps and the sha256 of the canonical record. Order and evidence are written in the same transaction: there is no order without evidence.
GET .../p2p/orders/{orderId}/price-evidence returns the record to either party from the moment the order opens. verified says the hash still matches; orderPrice is the locked price and spotPrice the spot it came from. The same record goes into the contract (cotacao_binance, cotacao_horario, cotacao_evidencia_sha256) and is available to dispute analysis.
If Binance does not answer (timeout, error, rate limit, invalid response), opening responds 409 price_unavailable and nothing is created or locked; retry shortly with the same Idempotency-Key. Replaying an order that already exists does not query Binance again.
Lifecycle
With signing disabled in the market, the order goes from funded straight to signed.
Deadlines
CorpX adjusts the durations for the whole market. deadlineAt is always the deadline running now; in dispute or a final status, null. Use this field for the on-screen timer.
End-to-end purchase
Cancellation and fault
POST .../cancel with an optional reason:
- before signing their own copy, either party can cancel; the fault (
fault) is on whoever cancelled; - after both signatures, cancelling does not exist: the path is a dispute;
- an expired deadline cancels with the fault on whoever let it expire;
- refusing the signature cancels with the fault on whoever refused.
A cancelled order shows cancelledBy, fault and cancelReason. The amount returns to the buyer and the stock to the ad. The fault counts toward reputation.
Timeline
GET .../p2p/orders/{orderId} carries timeline: the order’s history from the point of view of whoever reads it. Each item has at, type, title, actor (buyer, seller, corpx or system), actorIsYou and data.
- The title comes ready-made in Portuguese and relative to the reader: “Você assinou o contrato” (you signed the contract), “A contraparte enviou a cripto” (the counterparty sent the crypto).
- The counterparty never appears by name or document, and the CorpX agent appears only as “CorpX”.
datacarries only the type’s public fields (amount, deadline, txid, confirmations, reason). The buyer sees the amount held and returned; whoever pays the fee sees the charge.
When the order is concluded
The order has concluded and concludedAt. It concludes when all of the following hold:
- it is
released, orresolvedwith the dispute decided for the seller; - both parties signed the contract (when signing is enabled);
- the payment to the seller was recorded;
- the fee was charged (when there is a fee).
A cancelled order, or one refunded to the buyer, does not conclude.
Receipt
GET .../p2p/orders/{orderId}/receipt answers only for a concluded order (otherwise, 409 order_not_concluded). It is the only place where the parties are identified: name, username and masked document (***.456.789-**, 12.345.678/****-**).
On the receipt, the timeline uses the parties’ names in the titles. The party’s own signed copy is at GET .../contract, available after release.