> This page is for Internet banking (beta).

> 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 — guia do internet banking

Este guia mapeia as telas de um internet banking com P2P Cripto para as chamadas da API e diz o que mostrar em cada uma. Tudo aqui vale para o IB da CorpX e para o de qualquer tenant.

## Mapa de telas

```mermaid
flowchart TD
    M["Mercado<br />GET /v1/p2p/ads"] --> D["Perfil do anunciante<br />GET /v1/p2p/profiles/{username}"]
    M --> AD["Anúncio<br />GET /v1/p2p/ads/{adId}"]
    AD --> O["Abrir ordem<br />POST .../p2p/orders"]
    O --> T["Tela da ordem<br />GET .../p2p/orders/{orderId}"]
    T --> A["Assinar<br />signatureUrl"]
    T --> X["Informar txid<br />POST .../txids"]
    T --> L["Liberar<br />POST .../release (PIN)"]
    T --> Q["Disputa<br />POST .../disputes"]
    T --> R["Comprovante<br />GET .../receipt"]
    E["Extrato<br />GET .../statement"] --> ED["Detalhe da linha<br />p2pNegotiation"]
    ED --> T
    S["Saldo<br />heldAmount"] --> H["Bloqueios<br />GET .../holds?status=held"]
    H --> T
    P["Perfil e carteiras<br />GET .../p2p/profile, .../p2p/wallets"] --> M
    MY["Meus anúncios<br />GET .../p2p/ads"] --> MYE["Criar e editar<br />POST, PATCH .../p2p/ads"]
```

## Abrir ordem

Carregue o anúncio por `GET /v1/p2p/ads/{adId}`, não pelo item da lista: assim a tela abre por link direto e volta depois de recarregar. O detalhe traz os campos do item da lista mais `network`, `asset` e `decimals` do par. `404 ad_not_found` quer dizer que o anúncio saiu do livro: volte ao mercado. Para abrir a ordem, mande sempre `walletId`, a carteira do cliente na rede do par; a API decide pelo lado do anúncio qual carteira é a de origem e qual é a de destino.

## Tela da ordem

* **Cabeçalho:** par, `cryptoAmount`, `price`, `amount`, status e o cronômetro com `deadlineAt` (some quando é `null`).
* **Valores:** o comprador vê `heldAmount` (o que saiu do saldo); o vendedor vê `netAmount` (o que vai receber). Mostre `fee` e diga quem paga pelo `feePayer`.
* **Contraparte:** só `counterparty.username` e a reputação. Nunca peça nem mostre o nome antes do comprovante.
* **Ação do momento:**

| Status                              | Comprador                                          | Vendedor                                           |
| ----------------------------------- | -------------------------------------------------- | -------------------------------------------------- |
| `signing`                           | Assinar (se `signatureUrl` veio), cancelar         | Aguardar, cancelar antes de assinar                |
| `signed`                            | Aguardar o envio; disputar                         | Enviar para `destinationAddress` e informar o txid |
| `crypto_sent`                       | Acompanhar as confirmações; liberar se já conferiu | Aguardar; disputar depois de 60 min                |
| `crypto_confirmed`                  | Liberar com o PIN                                  | Aguardar; disputar depois de 24 h                  |
| `disputed`                          | Mensagens e evidências                             | Mensagens e evidências                             |
| `released`, `resolved`, `cancelled` | Comprovante (se concluída)                         | Comprovante (se concluída)                         |

* **Timeline:** liste `timeline` como veio, do mais antigo para o mais novo. O `title` já está pronto e relativo a quem lê; destaque `actorIsYou`.
* **Txids:** para cada txid, `checkStatus`, `confirmations` e um link para o explorador da rede.

Atualize a tela pelo webhook `p2p.order.updated` (ou pelo `GET` da ordem); não calcule status no cliente.

## Extrato e saldo

* Linhas com `partnerType: P2P_CRYPTO_ORDER` têm `p2pOrderId`. Use-o para abrir a tela da ordem a partir do extrato.
* O detalhe da linha já traz `p2pNegotiation` com a timeline e, se a ordem concluiu, o `receipt`. Uma chamada basta para mostrar a negociação.
* A contraparte é sempre `ORDEM P2P CRIPTO`. Não tente resolver o nome por outro caminho.
* No saldo, mostre `heldAmount` como "bloqueado" e leve à lista `GET .../holds?status=held`; cada hold de ordem tem `source.orderId` e `source.deadlineAt`.

## Comprovante

Só existe com `concluded: true`. Mostre as duas partes com nome, `username` e documento mascarado como veio (não desmascare nem reformate), os txids com o explorador, o pagamento e a taxa com os identifiers e o horário de cada passo. A via assinada da parte sai de `GET .../contract`, por link temporário.

## Erros que a tela trata

| Código                           | O que mostrar                                                                                                                                                                                |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `feature_disabled`               | Esconda a seção P2P.                                                                                                                                                                         |
| `wallet_not_approved`            | Na abertura, `details.walletOf` diz se a carteira recusada é a de quem toma (`taker`) ou a do anunciante (`maker`). Se for a sua, peça outra; se for a do anunciante, ofereça outro anúncio. |
| `insufficient_available_balance` | Saldo insuficiente para o bloqueio.                                                                                                                                                          |
| `order_step_out_of_order`        | Recarregue a ordem: o passo já mudou.                                                                                                                                                        |
| `dispute_not_allowed_yet`        | Mostre quando a disputa fica disponível.                                                                                                                                                     |
| `release_failed`                 | O valor segue bloqueado e a CorpX está refazendo; não peça nova liberação.                                                                                                                   |
| `order_not_concluded`            | Comprovante ainda indisponível.                                                                                                                                                              |
| `ad_suspended`                   | O anúncio foi suspenso pela CorpX; fale com o suporte.                                                                                                                                       |
| `ad_unavailable`                 | Na abertura, o anúncio saiu do livro (inclusive porque o anunciante está fora do horário de saída dele); volte ao mercado.                                                                   |
| `cashout_locked`                 | Em criar ou religar anúncio de compra: a saída da conta está bloqueada; leve às travas de segurança. Em "Meus anúncios", mostre `hiddenReason` como "fora do mercado agora".                 |

Lista completa na seção **P2P Cripto** de [Tratamento de Erros](/baas/guias/referencia/erros).