MIGI TRUST HUB / docs / api-b2b

API B2B

Integre escrow Web3 com pagamento Pix diretamente na sua plataforma. REST API com autenticação via API Key, respostas em JSON e webhooks em tempo real.

v1.0.0 — estável · Base URL: api.migitrust.io
BASE URL
https://api.migitrust.io/v1
✦ Sobre a API

Todos os endpoints retornam JSON. As requisições com body devem usar Content-Type: application/json. Timestamps são retornados em ISO 8601 (UTC). Valores monetários em centavos (BRL).

Autenticação

Todas as requisições exigem uma API Key no header Authorization. Gere sua chave no painel em Configurações → API Keys.

🔑
Authorization: Bearer migi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Prefixo migi_live_ para produção · migi_test_ para sandbox
⚠ Segurança

Nunca exponha sua API Key no frontend. Use sempre pelo backend. Em caso de comprometimento, revogue imediatamente no painel e gere uma nova chave.

exemplo — autenticação
// cURL
curl -X GET https://api.migitrust.io/v1/acordos \
  -H "Authorization: Bearer migi_live_sk_..." \
  -H "Content-Type: application/json"

Rate Limits

Os limites são por API Key, por minuto. O header X-RateLimit-Remaining informa o saldo atual.

FREE
60
req / minuto
PRO
600
req / minuto
BUSINESS
∞
sob contrato
headers de resposta
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1709500800

Erros

Erros seguem um formato padrão com código HTTP e payload JSON descritivo.

formato de erro
{
  "erro": {
    "codigo": "SALDO_INSUFICIENTE",
    "mensagem": "Saldo insuficiente na wallet do pagador",
    "status": 422,
    "timestamp": "2026-03-01T14:22:00Z",
    "request_id": "req_9f3kXp2mW"
  }
}
200OK — sucesso
201Created — recurso criado
400Bad Request — payload inválido
401Unauthorized — API Key inválida
403Forbidden — sem permissão
404Not Found — recurso não existe
422Unprocessable — erro de negócio
429Too Many Requests — rate limit
500Server Error — erro interno

Acordos / Escrow

POST /acordos Cria novo escrow entre pagador e beneficiário ▶
Body — application/json
Campo Tipo Obr. Descrição
titulo string sim Nome do acordo (max 120 chars)
valor_centavos integer sim Valor em centavos BRL. Ex: R$150,00 = 15000
wallet_beneficiario string sim Endereço Solana do beneficiário (base58, 44 chars)
descricao string não Descrição livre do escopo (max 2000 chars)
prazo_dias integer não Dias para expiração automática (padrão: 30)
milestones array não Lista de etapas com valor e descrição
metadata object não Dados livres (até 4kb) para uso interno 
{
  "titulo": "Desenvolvimento Landing Page",
  "valor_centavos": 350000,
  "wallet_beneficiario": "7xKXtg2CW...",
  "descricao": "Entrega do design e código em 15 dias",
  "prazo_dias": 15,
  "milestones": [
    { "descricao": "Design aprovado", "valor_centavos": 150000 },
    { "descricao": "Código entregue", "valor_centavos": 200000 }
  ],
  "metadata": { "pedido_id": "PED-2026-001" }
}

{
  "id": "agr_8fXp3mKj9W",
  "status": "aguardando_pagamento",
  "titulo": "Desenvolvimento Landing Page",
  "valor_centavos": 350000,
  "taxa_centavos": 5215,
  "wallet_pagador": "3hRz9Kp1...",
  "wallet_beneficiario": "7xKXtg2CW...",
  "wallet_escrow": "EsCroW11111...",
  "tx_hash": null,
  "pix_link": "https://api.migitrust.io/v1/pix/agr_8fXp3mKj9W",
  "expires_at": "2026-03-16T00:00:00Z",
  "criado_em": "2026-03-01T10:00:00Z"
}
GET /acordos Lista acordos da conta com filtros e paginação ▶
Query Params
Param Tipo Obr. Descrição
status string não aguardando_pagamento · ativo · concluido · cancelado · disputa
page integer não Página (padrão: 1)
limit integer não Itens por página, máx 100 (padrão: 20)
de date não Data inicial (ISO 8601, ex: 2026-01-01)
ate date não Data final (ISO 8601)
response 200
{
  "dados": [
    {
      "id": "agr_8fXp3mKj9W",
      "titulo": "Desenvolvimento Landing Page",
      "valor_centavos": 350000,
      "status": "ativo",
      "criado_em": "2026-03-01T10:00:00Z"
    }
  ],
  "paginacao": {
    "total": 47,
    "pagina": 1,
    "limite": 20,
    "proxima": "https://api.migitrust.io/v1/acordos?page=2"
  }
}
GET /acordos/{id} Retorna detalhes completos de um acordo ▶
Path Params
Param Tipo Obr. Descrição
id string sim ID do acordo (prefixo agr_)
response 200
{
  "id": "agr_8fXp3mKj9W",
  "status": "ativo",
  "titulo": "Desenvolvimento Landing Page",
  "descricao": "Entrega do design e código em 15 dias",
  "valor_centavos": 350000,
  "taxa_centavos": 5215,
  "wallet_escrow": "EsCroW11111...",
  "tx_hash": "5Kj8mW3xP...",
  "milestones": [
    { "id": 1, "descricao": "Design aprovado", "valor_centavos": 150000, "status": "concluido" },
    { "id": 2, "descricao": "Código entregue", "valor_centavos": 200000, "status": "pendente" }
  ],
  "fairscore_beneficiario": 94,
  "expires_at": "2026-03-16T00:00:00Z",
  "criado_em": "2026-03-01T10:00:00Z",
  "atualizado_em": "2026-03-05T09:22:00Z",
  "metadata": { "pedido_id": "PED-2026-001" }
}
PUT /acordos/{id}/aprovar Pagador aprova entrega — libera fundos on-chain ▶
Body — opcional (milestone parcial)
Campo Tipo Obr. Descrição
milestone_id integer não Se informado, aprova apenas esta etapa
avaliacao integer não Nota 1–5 que compõe o FairScore do beneficiário
comentario string não Feedback registrado on-chain (max 500 chars)
response 200
{
  "id": "agr_8fXp3mKj9W",
  "status": "concluido",
  "tx_liberacao": "9mPq4jX2L...",
  "valor_liberado_centavos": 350000,
  "concluido_em": "2026-03-10T14:30:00Z"
}
POST /acordos/{id}/disputar Abre disputa — aciona árbitro MIGI ▶
Body
Campo Tipo Obr. Descrição
motivo string sim Descrição do motivo da disputa (max 2000 chars)
evidencias array não URLs de arquivos/prints como evidência
⚠ Prazo de resposta

A outra parte tem 48 horas para contra-argumentar. Após isso, o árbitro MIGI analisa e decide em até 5 dias úteis.

DEL /acordos/{id} Cancela acordo (só se ainda não pago) ▶
⛔ Atenção

Acordos com status ativo (já pagos) não podem ser cancelados via API — abra uma disputa.

response 200
{
  "id": "agr_8fXp3mKj9W",
  "status": "cancelado",
  "cancelado_em": "2026-03-02T08:00:00Z"
}

Pagamentos

POST /pagamentos/pix Gera QR Code Pix para financiar um acordo ▶
Body
Campo Tipo Obr. Descrição
acordo_id string sim ID do acordo a financiar
expiracao_minutos integer não Validade do QR (padrão: 30, máx: 1440) 
{ "acordo_id": "agr_8fXp3mKj9W", "expiracao_minutos": 60 }

{
  "pix_id": "pix_3hRzKp1mW",
  "acordo_id": "agr_8fXp3mKj9W",
  "valor_centavos": 350000,
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_url": "https://api.migitrust.io/v1/pix/pix_3hRzKp1mW/qr.png",
  "copia_cola": "00020126580014br.gov.bcb.pix0136...",
  "status": "pendente",
  "expira_em": "2026-03-01T11:00:00Z"
}
GET /pagamentos/pix/{pix_id} Consulta status de um Pix gerado ▶
response 200
{
  "pix_id": "pix_3hRzKp1mW",
  "status": "pago",
  "valor_centavos": 350000,
  "pago_em": "2026-03-01T10:47:33Z",
  "tx_on_chain": "5Kj8mW3xP..."
}
GET /wallet/saldo Retorna saldo em escrow e disponível na wallet ▶
response 200
{
  "wallet": "3hRz9Kp1...",
  "saldo_disponivel_centavos": 84520,
  "saldo_em_escrow_centavos": 350000,
  "migi_tokens": 1250.00,
  "atualizado_em": "2026-03-01T10:00:00Z"
}

Reputação · FairScale

GET /reputacao/{wallet}/fairscore Retorna FairScore on-chain de uma wallet ▶
response 200
{
  "wallet": "7xKXtg2CW...",
  "fairscore": 94,
  "nivel": "Diamante",
  "acordos_concluidos": 38,
  "acordos_disputados": 1,
  "taxa_sucesso": 97.4,
  "volume_total_centavos": 12450000,
  "avaliacao_media": 4.8,
  "membro_desde": "2025-06-01"
}
GET /reputacao/{wallet}/historico Histórico de acordos on-chain paginado ▶
response 200
{
  "wallet": "7xKXtg2CW...",
  "dados": [
    {
      "acordo_id": "agr_8fXp3mKj9W",
      "titulo": "Desenvolvimento Landing Page",
      "valor_centavos": 350000,
      "status": "concluido",
      "avaliacao": 5,
      "tx_hash": "5Kj8mW3xP...",
      "concluido_em": "2026-03-10T14:30:00Z"
    }
  ],
  "paginacao": { "total": 38, "pagina": 1, "limite": 20 }
}

Webhooks

Configure uma URL para receber notificações em tempo real sobre eventos dos seus acordos. O MIGI enviará um POST com payload JSON e header X-Migi-Signature para verificação.

configurar via API — POST /webhooks
{
  "url": "https://seuapp.com/webhooks/migi",
  "eventos": [
    "acordo.pago",
    "acordo.concluido",
    "acordo.disputa_aberta"
  ],
  "ativo": true
}

Eventos disponíveis

acordo.criadoNovo acordo criado — aguardando pagamento
acordo.pagoPix confirmado — fundos bloqueados no escrow
acordo.aprovadoEntrega aprovada pelo pagador
acordo.concluidoFundos liberados on-chain ao beneficiário
acordo.canceladoAcordo cancelado antes do pagamento
acordo.disputa_abertaDisputa aberta por uma das partes
acordo.disputa_resolvidaÁrbitro encerrou a disputa com decisão
acordo.expiradoAcordo não pago dentro do prazo
pix.geradoQR Code Pix gerado para um acordo
pix.expiradoQR Code Pix expirou sem pagamento

Verificar assinatura

Cada webhook inclui o header X-Migi-Signature com HMAC-SHA256 do payload usando seu webhook secret. Valide sempre antes de processar.

verificação — Node.js
// Seu webhook secret está no painel → Configurações → Webhooks
const crypto = require('crypto');

function verificarAssinatura(payload, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(hmac),
    Buffer.from(signature.replace('sha256=', ''))
  );
}
payload de evento exemplo
{
  "evento": "acordo.concluido",
  "timestamp": "2026-03-10T14:30:00Z",
  "webhook_id": "wh_5mNpKj2X",
  "dados": {
    "acordo_id": "agr_8fXp3mKj9W",
    "status": "concluido",
    "valor_liberado_centavos": 350000,
    "tx_liberacao": "9mPq4jX2L..."
  }
}