> This page is for BaaS.

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

# P2P Cripto — ordens

Uma ordem é uma negociação sobre um anúncio. Quem toma o anúncio abre a ordem; o anunciante é a outra parte. Rotas em `/v1/accounts/{accountId}/p2p/orders`.

## Abertura

`POST .../p2p/orders` com `Idempotency-Key`, `adId`, `walletId` (opcional, senão a padrão) e `amount` (reais) **ou** `cryptoAmount`. Antes de responder `201`, a CorpX:

1. tria de novo as duas carteiras;
2. reserva o estoque do anúncio;
3. bloqueia o valor do comprador (o hold).

Se qualquer passo falha, a resposta é 4xx e nada fica travado. Na recusa de carteira (`422 wallet_not_approved`), `details.walletOf` diz de quem é: `taker` (quem abriu) ou `maker` (o anunciante). A repetição com a mesma chave e o mesmo corpo devolve a mesma ordem.

## Preço da ordem e evidência

O preço é travado na abertura com uma consulta ao vivo ao preço spot da Binance (`GET /api/v3/ticker/price?symbol={ATIVO}BRL`), a única fonte de cotação do mercado. Anúncio com `spread` aplica os pontos-base sobre esse spot; anúncio com `offset` soma a diferença em reais (até 4 casas); anúncio com `fixed` mantém o preço fixo, mas a Binance é consultada do mesmo jeito, para registrar o mercado do momento. A consulta não usa cache: é a leitura daquele instante.

O preço por unidade fica com 4 casas (`5.4321`) na ordem, na evidência e no contrato. O valor em reais da ordem é que vira centavos, truncado (cripto × preço); a taxa arredonda ao centavo para cima.

A troca HTTP inteira fica guardada como **evidência da ordem**: request (método, URL, headers), resposta (status, todos os headers, corpo cru e `sha256` do corpo), transporte (IP remoto, sessão TLS e cadeia de certificados), horários com milissegundos e o `sha256` do registro canônico. Ordem e evidência são gravadas na mesma transação: não existe ordem sem evidência.

`GET .../p2p/orders/{orderId}/price-evidence` devolve o registro para qualquer uma das partes desde a abertura. `verified` diz se o hash ainda confere; `orderPrice` é o preço travado e `spotPrice` o spot que o gerou. O mesmo registro entra no contrato (`cotacao_binance`, `cotacao_horario`, `cotacao_evidencia_sha256`) e fica à disposição da análise de disputa.

Se a Binance não responde (tempo esgotado, erro, limite de requisições, resposta inválida), a abertura responde `409 price_unavailable` e nada é criado nem travado; repita em instantes com a mesma `Idempotency-Key`. A repetição de uma ordem que já existe não consulta a Binance de novo.

## Ciclo de vida

```mermaid
stateDiagram-v2
    [*] --> funded: abertura (valor bloqueado)
    funded --> signing: contrato enviado
    signing --> signed: as duas partes assinaram
    signing --> cancelled: recusa, cancelamento<br />ou prazo de assinatura vencido
    signed --> crypto_sent: vendedor informa o txid
    signed --> disputed: prazo de envio vencido<br />ou comprador disputa
    crypto_sent --> signed: txid não confere<br />(ainda no prazo)
    crypto_sent --> crypto_confirmed: confirmações atingidas
    crypto_sent --> released: comprador libera antes<br />das confirmações
    crypto_sent --> disputed: rede não confirma em 60 min<br />ou uma parte disputa
    crypto_confirmed --> released: comprador libera
    crypto_confirmed --> disputed: prazo de liberação vencido<br />ou uma parte disputa
    disputed --> resolved: CorpX decide
    released --> [*]
    cancelled --> [*]
    resolved --> [*]
```

Com a assinatura desligada no mercado, a ordem vai de `funded` direto para `signed`.

## Prazos

| Prazo                          | Campo               | Duração padrão                    | Ao vencer                                                                               |
| ------------------------------ | ------------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
| Assinatura do comprador        | `signingDeadlineAt` | 15 min do envio do contrato       | Cancela; falta do comprador.                                                            |
| Assinatura e envio do vendedor | `sellerDeadlineAt`  | 15 min da assinatura do comprador | Sem assinatura: cancela, falta do vendedor. Assinado sem txid: abre disputa automática. |
| Confirmação na rede            | `onchainDeadlineAt` | 60 min do txid                    | Abre disputa automática (`onchain_unconfirmed`).                                        |
| Liberação pelo comprador       | `releaseDeadlineAt` | 24 h da confirmação               | Abre disputa automática (`release_overdue`).                                            |

A CorpX ajusta as durações para o mercado inteiro. **`deadlineAt`** é sempre o prazo que corre agora; em disputa ou status final, `null`. Use esse campo para o cronômetro da tela.

## Compra de ponta a ponta

```mermaid
sequenceDiagram
    autonumber
    participant C as Comprador
    participant API as CorpX
    participant V as Vendedor
    participant R as Rede
    C->>API: POST /p2p/orders (adId, amount)
    API->>API: triagem, reserva de estoque, bloqueio
    API-->>C: 201 funded
    API-->>V: p2p.order.updated (funded)
    API-->>C: p2p.order.signature.requested
    C->>API: assina (signatureUrl)
    API-->>V: p2p.order.signature.requested
    V->>API: assina
    API-->>C: p2p.order.updated (signed)
    V->>R: envia a cripto para destinationAddress
    V->>API: POST .../txids
    API->>R: confere txid, valor, destino e confirmações
    API-->>C: p2p.order.txid.checked
    API-->>C: p2p.order.updated (crypto_confirmed)
    C->>API: POST .../release (PIN)
    API->>API: pagamento ao vendedor e taxa
    API-->>V: p2p.order.updated (released)
```

## Cancelamento e falta

`POST .../cancel` com `reason` opcional:

* antes de assinar a própria via, qualquer parte cancela; a **falta** (`fault`) fica com quem cancelou;
* depois das duas assinaturas, cancelar não existe: o caminho é a disputa;
* prazo vencido cancela com a falta de quem deixou vencer;
* recusa da assinatura cancela com a falta de quem recusou.

A ordem cancelada mostra `cancelledBy`, `fault` e `cancelReason`. O valor volta ao comprador e o estoque ao anúncio. A falta entra na reputação.

## Timeline

`GET .../p2p/orders/{orderId}` traz `timeline`: a história da ordem do ponto de vista de quem consulta. Cada item tem `at`, `type`, `title`, `actor` (`buyer`, `seller`, `corpx` ou `system`), `actorIsYou` e `data`.

* O título já sai pronto em português e relativo a quem lê: "Você assinou o contrato", "A contraparte enviou a cripto".
* A contraparte nunca aparece por nome nem documento, e o atendente da CorpX aparece só como "CorpX".
* `data` só traz campos públicos do tipo (valor, prazo, txid, confirmações, motivo). O comprador vê o valor bloqueado e devolvido; quem paga a taxa vê a cobrança.

```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" }
}
```

## Quando a ordem é concluída

A ordem tem `concluded` e `concludedAt`. Ela conclui quando **tudo** abaixo vale:

* está `released`, ou `resolved` com a disputa decidida para o vendedor;
* as duas partes assinaram o contrato (quando a assinatura está ligada);
* o pagamento ao vendedor foi gravado;
* a taxa foi cobrada (quando há taxa).

Ordem cancelada ou devolvida ao comprador não conclui.

## Comprovante

`GET .../p2p/orders/{orderId}/receipt` responde só para ordem concluída (senão, `409 order_not_concluded`). É o único lugar em que as partes se identificam: nome, `username` e documento **mascarado** (`***.456.789-**`, `12.345.678/****-**`).

```mermaid
flowchart TD
    Q["A parte consulta a ordem"] --> C{"concluded?"}
    C -- "não" --> A["Ordem e timeline<br />contraparte só com username e reputação"]
    C -- "sim" --> R["GET .../receipt"]
    R --> P["Nome e documento mascarado das duas partes<br />txids com link do explorador<br />pagamento e taxa com identifier"]
    A -. "nunca" .-> X["Nome, documento, conta<br />e dados da CorpX"]
```

```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": []
}
```

No comprovante, a timeline usa os nomes das partes nos títulos. A via assinada da própria parte fica em `GET .../contract`, disponível depois da liberação.