> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

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

1. screens both wallets again;
2. reserves the ad's stock;
3. 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

```mermaid
stateDiagram-v2
    [*] --> funded: opening (amount held)
    funded --> signing: contract sent
    signing --> signed: both parties signed
    signing --> cancelled: refusal, cancellation<br />or signing deadline expired
    signed --> crypto_sent: seller reports the txid
    signed --> disputed: transfer deadline expired<br />or buyer disputes
    crypto_sent --> signed: txid does not match<br />(still within the deadline)
    crypto_sent --> crypto_confirmed: confirmations reached
    crypto_sent --> released: buyer releases before<br />the confirmations
    crypto_sent --> disputed: network does not confirm in 60 min<br />or a party disputes
    crypto_confirmed --> released: buyer releases
    crypto_confirmed --> disputed: release deadline expired<br />or a party disputes
    disputed --> resolved: CorpX decides
    released --> [*]
    cancelled --> [*]
    resolved --> [*]
```

With signing disabled in the market, the order goes from `funded` straight to `signed`.

## Deadlines

| Deadline                      | Field               | Default duration                    | When it expires                                                                         |
| ----------------------------- | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------- |
| Buyer signature               | `signingDeadlineAt` | 15 min from the contract being sent | Cancels; buyer's fault.                                                                 |
| Seller signature and transfer | `sellerDeadlineAt`  | 15 min from the buyer's signature   | Not signed: cancels, seller's fault. Signed without a txid: opens an automatic dispute. |
| Network confirmation          | `onchainDeadlineAt` | 60 min from the txid                | Opens an automatic dispute (`onchain_unconfirmed`).                                     |
| Release by the buyer          | `releaseDeadlineAt` | 24 h from confirmation              | Opens an automatic dispute (`release_overdue`).                                         |

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

```mermaid
sequenceDiagram
    autonumber
    participant C as Buyer
    participant API as CorpX
    participant V as Seller
    participant R as Network
    C->>API: POST /p2p/orders (adId, amount)
    API->>API: screening, stock reservation, hold
    API-->>C: 201 funded
    API-->>V: p2p.order.updated (funded)
    API-->>C: p2p.order.signature.requested
    C->>API: signs (signatureUrl)
    API-->>V: p2p.order.signature.requested
    V->>API: signs
    API-->>C: p2p.order.updated (signed)
    V->>R: sends the crypto to destinationAddress
    V->>API: POST .../txids
    API->>R: checks txid, amount, destination and confirmations
    API-->>C: p2p.order.txid.checked
    API-->>C: p2p.order.updated (crypto_confirmed)
    C->>API: POST .../release (PIN)
    API->>API: payment to the seller and fee
    API-->>V: p2p.order.updated (released)
```

## 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".
* `data` carries 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.

```json
{
  "at": "2026-11-01T14:03:12Z",
  "type": "crypto_confirmed",
  "title": "Cripto confirmada na rede",
  "actor": "system",
  "actorIsYou": false,
  "data": { "releaseDeadlineAt": "2026-11-02T14:03:12Z" }
}
```

## When the order is concluded

The order has `concluded` and `concludedAt`. It concludes when **all** of the following hold:

* it is `released`, or `resolved` with 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/****-**`).

```mermaid
flowchart TD
    Q["The party reads the order"] --> C{"concluded?"}
    C -- "no" --> A["Order and timeline<br />counterparty only with username and reputation"]
    C -- "yes" --> R["GET .../receipt"]
    R --> P["Name and masked document of both parties<br />txids with explorer link<br />payment and fee with identifier"]
    A -. "never" .-> X["Name, document, account<br />and CorpX data"]
```

```json
{
  "orderId": "ord_4235120236fa625f2a539d0c",
  "concluded": true,
  "concludedAt": "2026-11-01T14:20:05Z",
  "role": "buyer",
  "order": {
    "pair": "USDT_TRON", "network": "tron", "cryptoAmount": "100", "price": "5.12",
    "amount": "512.00", "fee": "2.56", "feePayer": "seller", "sellerNetAmount": "509.44",
    "status": "released", "openedAt": "2026-11-01T13:40:00Z"
  },
  "parties": [
    { "role": "buyer", "name": "Fulana de Tal", "document": "***.456.789-**", "username": "fulana", "isYou": true },
    { "role": "seller", "name": "Ciclano Ltda", "document": "12.345.678/****-**", "username": "ciclano", "isYou": false }
  ],
  "crypto": {
    "destinationAddress": "TB…", "senderAddress": "TS…",
    "txids": [{ "txid": "9f1c…", "network": "tron", "checkStatus": "confirmed", "confirmations": 19,
                "explorerUrl": "https://tronscan.org/#/transaction/9f1c…", "screening": "approved" }]
  },
  "contract": {
    "buyer": { "status": "signed", "signedAt": "2026-11-01T13:45:00Z", "sha256": "…" },
    "seller": { "status": "signed", "signedAt": "2026-11-01T13:52:00Z", "sha256": "…" },
    "downloadPath": "/v1/accounts/{accountId}/p2p/orders/ord_4235120236fa625f2a539d0c/contract"
  },
  "money": {
    "hold": { "amount": "512.00", "at": "2026-11-01T13:40:01Z" },
    "payment": { "identifier": "p2p-ord_4235120236fa625f2a539d0c", "amount": "512.00", "partnerTransactionId": "…", "at": "2026-11-01T14:20:00Z" },
    "fee": { "identifier": "fee-p2p-ord_4235120236fa625f2a539d0c", "amount": "2.56", "payer": "seller",
             "destination": "Conta de intermediação CorpX", "at": "2026-11-01T14:20:04Z" }
  },
  "timeline": []
}
```

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.