Referência técnica - BrightCity Chain

Esta página reúne os identificadores mais usados por integrações e suporte. A referência interativa da API fica em BrightCity Energy API.

Endpoints públicos do Gateway

Grupo	Rotas
Saúde	`GET /health`, `GET /ready`
Autenticação	`GET /auth/authorize`, `GET /auth/callback`, `POST /auth/complete-callback`, `POST /auth/exchange-session`, `POST /auth/refresh`, `POST /auth/login`, `GET /auth/me`
Perfil	`GET /me`, `GET /admin-only`
Sensores	`GET /sensors`, `POST /sensors`, `GET /sensors/{sensor_id}`, `PATCH /sensors/{sensor_id}`
Políticas	`GET /sensors/{sensor_id}/price-policy`, `POST /sensors/{sensor_id}/price-policy`, `PUT /sensors/{sensor_id}/price-policy`
Medições	`POST /measurements`, `POST /meters/measurement`, `GET /sensors/{sensor_id}/measurements`
Transações	`POST /transactions/account`, `POST /transactions/receipts`, `GET /transactions/{tx_hash}/events`
Carteira	`GET /wallet/bridge-info`, `GET /wallet/deposit-requests`, `POST /wallet/deposit-requests`, `PATCH /wallet/deposit-requests/{deposit_id}/reference`, `POST /wallet/deposit-requests/{deposit_id}/confirm`, `POST /wallet/deposit-requests/{deposit_id}/cancel`
Mercado	`GET /offers`, `GET /orders`, `GET /trades`
Eventos	`GET /events`

Rotas internas por serviço

Serviço	Rotas principais
Auth	`/internal/sensor-admins`, `/internal/sensor-admins/check`
Meters	`/internal/sensors`, `/internal/sensors/register-boot`, `/internal/sensors/by-device/{device_id}`, `/internal/sensors/{sensor_id}`, `/internal/measurements`
Market	`/internal/evaluate-measurements`, `/internal/trades/{trade_id}/receipt`, `/internal/trades/{trade_id}/error`
Transactions	`/internal/euro/mint`, `/internal/sensors/register-on-chain`, `/internal/energy/payments/prepare`, `/internal/payments/pending`, `/internal/transactions/{tx_hash}`
Oracle	`/deposit-requests`, `/deposit-requests/{id}`, `/deposit-requests/{id}/confirm-bridge`, `/deposit-requests/{id}/cancel`
Indexer	`/events`, `/transactions/{tx_hash}/events`

Status

Sensor

Status	Significado
`active`	Estado por omissão; a actividade operacional no UI deriva de `last_communication_at` (15 min)
`blocked`	Não aceita medições (kill-switch interno)

Oferta

Status	Significado
`OPEN`	Disponível para matching
`RESERVED`	Reservada para um trade
`SOLD`	Vendida
`CANCELLED`	Cancelada

Ordem

Status	Significado
`OPEN`	Aguardando oferta compatível
`FILLED`	Casada com oferta
`CANCELLED`	Cancelada
`FAILED`	Falha operacional

Trade

Status	Significado
`PENDING_PAYMENT`	Aguardando assinatura e recibo do token privado
`PAID`	Pagamento validado
`ERROR`	Falha no pagamento ou atualização

Transação

Status	Significado
`PENDING`	Enviada e aguardando recibo
`PREPARED`	Sem assinatura, pronta para o device
`CONFIRMED`	Confirmada on-chain
`FAILED`	Falhou ou foi invalidada

Depósito

Status	Significado
`PENDING`	Aguardando confirmação
`APPROVED`	Creditado na Besu privada
`REJECTED`	Rejeitado
`EXPIRED`	Expirado
`CANCELLED`	Cancelado

Eventos on-chain indexados

Contrato	Evento	Origem
`EuroToken`	`EuroMinted`	Crédito via bridge
`SensorRegistry`	`SensorRegistered`	Boot ou registo de sensor
`EnergyMarket`	`EnergyOfferCreated`	Oferta on-chain
`EnergyMarket`	`EnergyOfferPurchased`	Compra on-chain
`EnergySettlement`	`SettlementCreated`	Liquidação on-chain

Limites e padrões

Item	Valor
Chain ID da BrightCity Chain	`20260520`
Token privado `EuroToken`	Nome `Euro Token`, símbolo `EURT`, 18 casas decimais
Token externo do bridge	EURC na rede principal configurada, 6 casas decimais no ambiente atual
Envio de dados do device	A cada 15 minutos
Ciclo de matching (Celery Beat)	15 minutos (`MATCHING_CYCLE_MINUTES`)
Poll do indexer (Celery Beat)	30 segundos (`INDEXER_POLL_SECONDS`)
Poll de expiração de depósitos (Celery Beat)	15 minutos (`DEPOSIT_EXPIRY_POLL_MINUTES`)
Broker Celery	Redis dedicado por serviço (market / indexer / oracle)
Janela interna de medição	Máximo de 60 minutos
Medição no futuro	Máximo de 15 minutos
Limite padrão de eventos	100
Limite máximo de eventos	500
Porta gRPC Meters	`5049`
Porta gRPC Transactions	`5050`
Porta gRPC Market	`5051`

Códigos de erro frequentes

Código	Significado
`MISSING_SENSOR_HEADERS`	Headers de medição ausentes
`SENSOR_HEADER_MISMATCH`	Sensor do header não coincide com o payload
`INVALID_SENSOR_SIGNATURE`	HMAC inválido
`SENSOR_NOT_ACTIVE`	Sensor bloqueado
`SENSOR_FORBIDDEN`	Usuário sem permissão no sensor
`DUPLICATE_MEASUREMENT_TIMESTAMP`	Medição duplicada para sensor e timestamp
`PRICE_POLICY_ALREADY_EXISTS`	Política já existe para o sensor
`PRICE_POLICY_NOT_FOUND`	Política não encontrada
`ENERGY_OFFER_ALREADY_EXISTS`	Oferta já existe para a medição
`ENERGY_ORDER_ALREADY_EXISTS`	Ordem já existe para a medição
`PAYMENT_NOT_FOUND`	Pagamento preparado não encontrado
`INVALID_TRANSFER`	Recibo não contém transferência esperada do `EuroToken`
`INVALID_SIGNER`	Transação assinada por carteira diferente do comprador
`DEPOSIT_NOT_PENDING`	Pedido de depósito não está pendente
`TRANSFER_NOT_FOUND`	Bridge não encontrou transferência válida
`DEVICE_WALLET_MISMATCH`	`deviceId` já registrado com outra carteira

Contratos on-chain

Contrato	Regras principais
`EuroToken`	ERC-20 `Euro Token`, símbolo `EURT`, 18 decimais, `MINTER_ROLE` para mint
`SensorRegistry`	`sensorId` e wallet não podem ser vazios, sensor novo começa habilitado
`EnergyMarket`	Oferta exige seller, kWh e preço positivos; status on-chain: `OPEN`, `SOLD`, `CANCELLED`
`EnergySettlement`	Liquidação exige comprador, vendedor, kWh e preço positivos

BrightCity Energy API

Abrir a referência REST interativa