GoldStay APIs Públicas - Documentação Enterprise

Visão Geral Enterprise

As APIs públicas do GoldStay fornecem acesso programático aos dados de reservas de ouro, cadeia de provas blockchain e preços em tempo real. Desenvolvidas seguindo padrões enterprise com arquitetura REST, autenticação robusta e documentação OpenAPI completa.

Base URL

https://api.goldstay.space/v1

Característica	Especificação	Detalhes
Protocolo	HTTPS/REST	TLS 1.3, certificados EV
Formato	JSON	UTF-8, Content-Type: application/json
Rate Limiting	1000 req/min	Headers: X-RateLimit-*
Cache	300 segundos	ETag, Cache-Control headers
Versionamento	v1	Backward compatibility garantida

Autenticação Segurança

As APIs públicas do GoldStay são abertas e não requerem autenticação para endpoints de leitura. Para uso enterprise com quotas elevadas, API keys estão disponíveis.

Exemplo com API Key

curl -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     https://api.goldstay.space/v1/reserves/current

Header	Valor	Obrigatório	Descrição
X-API-Key	string	Não	API key para quotas elevadas
Content-Type	application/json	Sim	Tipo de conteúdo
User-Agent	string	Recomendado	Identificação da aplicação

Rate Limits

Implementamos rate limiting para garantir disponibilidade e performance para todos os usuários. Os limites são aplicados por IP e incluem headers informativos na resposta.

Tipo de Usuário	Requests/Minuto	Burst Limit	Header
Público	100	150	X-RateLimit-Limit: 100
API Key	1000	1500	X-RateLimit-Limit: 1000
Enterprise	5000	7500	X-RateLimit-Limit: 5000

Headers de Rate Limiting

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 60

Códigos de Erro

A API utiliza códigos de status HTTP convencionais e retorna mensagens de erro estruturadas em formato JSON com informações detalhadas para debugging.

Código	Status	Descrição	Ação Recomendada
200	OK	Sucesso	-
400	Bad Request	Parâmetros inválidos	Verificar documentação
401	Unauthorized	API key inválida	Verificar autenticação
429	Too Many Requests	Rate limit excedido	Implementar backoff
500	Internal Server Error	Erro interno	Tentar novamente

Estrutura de Erro

{
  "status": "error",
  "timestamp": "2024-01-15T10:30:00Z",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "details": [
      {
        "field": "limit",
        "message": "Must be between 1 and 200"
      }
    ],
    "trace_id": "req_123abc456def"
  },
  "metadata": {
    "version": "v1",
    "response_time_ms": 45
  }
}

API de Reservas de Ouro Tempo Real

Acesso às informações de reservas físicas de ouro, distribuição por cofres, histórico de auditorias e provas criptográficas de integridade. Dados atualizados em tempo real com verificação blockchain.

GET /reserves/current

Reservas Atuais

Retorna o estado atual das reservas de ouro físico, incluindo distribuição por cofres, ratios de reserva e provas criptográficas opcionais.

Parâmetros de Query

include_proof boolean Incluir prova criptográfica
format string full | compact | summary

GET /reserves/audit-history

Histórico de Auditorias

Histórico completo de auditorias físicas realizadas nos cofres, incluindo datas, firmas auditoras e resultados das verificações.

Parâmetros de Query

from_date string Data início (ISO 8601)
to_date string Data fim (ISO 8601)
limit integer Máximo 200 itens

200 OK Exemplo de Resposta - Reservas Atuais

GET /reserves/current?format=full

{
  "status": "success",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "total_reserves": {
      "physical_gold_ounces": 1000.5,
      "tokenized_gold_ounces": 950.3,
      "reserve_ratio_percentage": 105.28
    },
    "vault_distribution": [
      {
        "vault_id": "LDN_001",
        "location": "London",
        "physical_ounces": 400.2,
        "security_level": "MAXIMUM",
        "custodian": "Brink's Global",
        "last_audit": "2024-01-10T00:00:00Z",
        "audit_firm": "KPMG"
      }
    ]
  },
  "metadata": {
    "version": "v1",
    "response_time_ms": 156,
    "cache_ttl_seconds": 300
  }
}

API de Cadeia de Provas Blockchain

Acesso à cadeia de provas blockchain que valida a integridade das reservas. Inclui validação de merkle trees, verificação de assinaturas e status de health da cadeia.

GET /audit/proof-chain

Cadeia de Provas

Retorna a cadeia completa de provas criptográficas, incluindo merkle trees, assinaturas e metadados de verificação blockchain.

Parâmetros de Query

limit integer 1-200 provas
proof_type string PERIODIC | TRIGGERED | EMERGENCY
verification_depth string BASIC | FULL | DEEP

GET /audit/integrity

Validação de Integridade

Executa validação completa da integridade da cadeia de provas, verificando assinaturas, merkle trees e continuidade da cadeia.

Parâmetros de Query

check_signatures boolean Verificar assinaturas
max_depth integer Profundidade da verificação

GET /audit/health

Status de Saúde

Status em tempo real da cadeia de provas, incluindo sincronização blockchain, métricas de performance e indicadores de saúde do sistema.

Sem Parâmetros

Este endpoint não aceita parâmetros de query.

API de Smart Contracts Multi-Chain

Informações sobre smart contracts do GoldStay implantados em múltiplas redes blockchain, incluindo endereços, status de verificação e análises de segurança.

GET /contracts/addresses

Endereços dos Contratos

Lista completa de endereços de smart contracts em todas as redes suportadas, incluindo contratos core, oráculos e governança.

Parâmetros de Query

network string mainnet | polygon | arbitrum | all
include_abi boolean Incluir ABI dos contratos
format string full | addresses_only

GET /contracts/verification

Status de Verificação

Status de verificação dos smart contracts em exploradores de blockchain como Etherscan, incluindo detalhes de compilação e código fonte.

Parâmetros de Query

verification_source string etherscan | sourcify | all
include_details boolean Detalhes de compilação

GET /contracts/security

Análise de Segurança

Relatórios de segurança e auditoria dos smart contracts, incluindo scores de segurança, vulnerabilidades conhecidas e recomendações.

Parâmetros de Query

include_breakdown boolean Breakdown por contrato
include_recommendations boolean Recomendações de segurança

API de Oráculo de Preços Tempo Real

Preços de ouro em tempo real agregados de múltiplas fontes confiáveis, incluindo Chainlink, Pyth Network e APIs de mercado. Suporte a múltiplas moedas e unidades de medida.

GET /price/oracle

Preço do Ouro

Preço atual do ouro agregado de múltiplas fontes com métodos de agregação configuráveis e dados históricos opcionais.

Parâmetros de Query

currency string USD | EUR | BTC | ETH
unit string troy_ounce | gram | kilogram
aggregation string MEDIAN | MEAN | TWAP | VWAP
include_history boolean Incluir dados históricos

GET /price/sources

Fontes de Preços

Status e informações das fontes de preços utilizadas, incluindo Chainlink, Pyth Network, DIA e APIs de mercado tradicionais.

Parâmetros de Query

source_type string CHAINLINK | PYTH | ALL
status string healthy | degraded | offline
include_metadata boolean Metadados das fontes

GET /price/convert/{currency}

Conversão de Preços

Conversão de quantidades de ouro para diferentes moedas usando taxas de câmbio atuais e preços de ouro em tempo real.

Parâmetros de Path

currency string Moeda de destino (USD, EUR, BTC)

Parâmetros de Query

amount number Quantidade de ouro
unit string troy_ounce | gram

200 OK Exemplo de Resposta - Preço do Ouro

GET /price/oracle?currency=USD&unit=troy_ounce

{
  "status": "success",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "aggregated_price": {
      "value_usd": 2045.67,
      "confidence_percentage": 96.5,
      "last_update": "2024-01-15T10:29:45Z",
      "aggregation_method": "MEDIAN"
    },
    "sources": [
      {
        "source_id": "chainlink_primary",
        "price_usd": 2044.12,
        "confidence": 98.2,
        "status": "healthy",
        "latency_ms": 156
      }
    ],
    "market_metadata": {
      "currency": "USD",
      "unit": "troy_ounce",
      "data_freshness_seconds": 15
    }
  }
}

Exemplos de Código

Exemplos práticos de integração com as APIs do GoldStay em diferentes linguagens de programação.

JavaScript / Node.js

// Exemplo: Buscar reservas atuais com JavaScript
const API_BASE = 'https://api.goldstay.space/v1';

async function getCurrentReserves() {
  try {
    const response = await fetch(`${API_BASE}/reserves/current?format=full`, {
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key' // Opcional
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const data = await response.json();

    console.log('Reservas atuais:', data.data.total_reserves);
    console.log('Distribuição por cofres:', data.data.vault_distribution);

    return data;
  } catch (error) {
    console.error('Erro ao buscar reservas:', error);
    throw error;
  }
}

// Exemplo: Monitorar preço do ouro
async function monitorGoldPrice() {
  const response = await fetch(`${API_BASE}/price/oracle?currency=USD&unit=troy_ounce`);
  const data = await response.json();

  console.log(`Preço do ouro: $${data.data.aggregated_price.value_usd}/oz`);
  console.log(`Confiança: ${data.data.aggregated_price.confidence_percentage}%`);
}

getCurrentReserves();
setInterval(monitorGoldPrice, 30000); // Atualizar a cada 30 segundos

Python

import requests
import json
from datetime import datetime

class GoldStayAPI:
    def __init__(self, api_key=None):
        self.base_url = "https://api.goldstay.space/v1"
        self.headers = {
            "Content-Type": "application/json",
            "User-Agent": "GoldStay-Python-Client/1.0"
        }
        if api_key:
            self.headers["X-API-Key"] = api_key

    def get_current_reserves(self, include_proof=False, format_type="full"):
        """Buscar reservas atuais de ouro"""
        params = {
            "include_proof": str(include_proof).lower(),
            "format": format_type
        }

        response = requests.get(
            f"{self.base_url}/reserves/current",
            headers=self.headers,
            params=params
        )
        response.raise_for_status()
        return response.json()

    def get_gold_price(self, currency="USD", unit="troy_ounce"):
        """Buscar preço atual do ouro"""
        params = {
            "currency": currency,
            "unit": unit,
            "aggregation": "MEDIAN"
        }

        response = requests.get(
            f"{self.base_url}/price/oracle",
            headers=self.headers,
            params=params
        )
        response.raise_for_status()
        return response.json()

    def get_proof_chain(self, limit=10, verification_depth="BASIC"):
        """Buscar cadeia de provas"""
        params = {
            "limit": limit,
            "verification_depth": verification_depth,
            "format": "FULL"
        }

        response = requests.get(
            f"{self.base_url}/audit/proof-chain",
            headers=self.headers,
            params=params
        )
        response.raise_for_status()
        return response.json()

# Exemplo de uso
api = GoldStayAPI(api_key="your-api-key")

# Buscar reservas
reserves = api.get_current_reserves(include_proof=True)
print(f"Total de ouro físico: {reserves['data']['total_reserves']['physical_gold_ounces']} oz")

# Buscar preço
price = api.get_gold_price()
print(f"Preço do ouro: ${price['data']['aggregated_price']['value_usd']:.2f}/oz")

# Verificar integridade da cadeia
proof_chain = api.get_proof_chain(limit=5)
print(f"Status da cadeia: {proof_chain['data']['chain_metadata']['chain_integrity']}")

cURL

# Exemplo: Buscar reservas atuais
curl -X GET "https://api.goldstay.space/v1/reserves/current?format=full&include_proof=true" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your-api-key"

# Exemplo: Buscar preço do ouro
curl -X GET "https://api.goldstay.space/v1/price/oracle?currency=USD&unit=troy_ounce&aggregation=MEDIAN" \
     -H "Content-Type: application/json"

# Exemplo: Verificar integridade da cadeia
curl -X GET "https://api.goldstay.space/v1/audit/integrity?check_signatures=true&max_depth=100" \
     -H "Content-Type: application/json"

# Exemplo: Buscar endereços de contratos
curl -X GET "https://api.goldstay.space/v1/contracts/addresses?network=mainnet&format=full" \
     -H "Content-Type: application/json"

# Exemplo: Conversão de preços
curl -X GET "https://api.goldstay.space/v1/price/convert/EUR?amount=1&unit=troy_ounce" \
     -H "Content-Type: application/json"

SDKs & Libraries

Libraries oficiais e da comunidade para facilitar a integração com as APIs do GoldStay em diferentes linguagens de programação.

Linguagem	Package	Status	Documentação
JavaScript/TypeScript	`@goldstay/api-client`	Oficial	Docs
Python	`goldstay-python`	Oficial	Docs
Go	`github.com/goldstay/go-client`	Beta	Docs
Rust	`goldstay-rs`	Planejado	-
Java	`com.goldstay:api-client`	Planejado	-

Webhooks

Receba notificações em tempo real sobre eventos importantes como mudanças nas reservas, novas provas na cadeia e atualizações de preços.

Evento	Descrição	Frequência	Payload
`reserves.updated`	Reservas atualizadas	Tempo real	Dados das reservas
`proof.generated`	Nova prova gerada	Tempo real	Dados da prova
`price.significant_change`	Mudança significativa no preço	Baseado em threshold	Dados de preço
`audit.completed`	Auditoria concluída	Conforme auditorias	Resultados da auditoria

Exemplo de Webhook Payload

{
  "event": "reserves.updated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "previous_total_ounces": 1000.5,
    "current_total_ounces": 1002.8,
    "change_ounces": 2.3,
    "change_reason": "vault_addition",
    "vault_id": "SIN_001"
  },
  "signature": "sha256=a8f5f167..."
}

Suporte & Recursos

Recursos adicionais para desenvolvedores, incluindo documentação técnica, comunidade e canais de suporte direto.

📚 Documentação Técnica

Guias detalhados, tutoriais e referência completa da API com exemplos práticos.

docs.goldstay.space →

💬 Comunidade

Junte-se à comunidade de desenvolvedores para trocar experiências e obter ajuda.

Discord Community →

🛠️ Postman Collection

Collection completa do Postman com todos os endpoints e exemplos de requests.

Download Collection →

🔧 OpenAPI Spec

Especificação OpenAPI 3.0 completa para geração automática de clients.

openapi.json →

📊 Status Page

Monitor em tempo real do status das APIs, uptime e métricas de performance.

status.goldstay.space →

📧 Suporte Direto

Para questões técnicas específicas, entre em contato com nossa equipe de engenharia.

api-support@goldstay.space →

Informações de Contato

📧 Email: api-support@goldstay.space
🌐 Website: https://goldstay.space
📚 Docs: https://docs.goldstay.space
📊 Status: https://status.goldstay.space
💬 Discord: https://discord.gg/goldstay
📱 Twitter: @goldstay_space

APIs Públicas GoldStay

Visão Geral Enterprise

Autenticação Segurança

Rate Limits

Códigos de Erro

API de Reservas de Ouro Tempo Real

Reservas Atuais

Histórico de Auditorias

API de Cadeia de Provas Blockchain

Cadeia de Provas

Validação de Integridade

Status de Saúde

API de Smart Contracts Multi-Chain

Endereços dos Contratos

Status de Verificação

Análise de Segurança

API de Oráculo de Preços Tempo Real

Preço do Ouro

Fontes de Preços

Conversão de Preços

Exemplos de Código

SDKs & Libraries

Webhooks

Suporte & Recursos

📚 Documentação Técnica

💬 Comunidade

🛠️ Postman Collection

🔧 OpenAPI Spec

📊 Status Page

📧 Suporte Direto