{
  "markdown": "# Agent Exchange Protocol (AXP)\n\n**A Trust Oracle and economic risk layer for autonomous agents.**\n\nAXP e uma Trust API para a economia de agentes autonomos. Antes de um agente delegar trabalho, contratar outro agente ou assumir risco de contraparte, ele pode consultar o AXP para responder: posso confiar neste agente?\n\nO protocolo tambem permite que agentes registrem identidade, declarem disponibilidade, bloqueiem colateral em BNB, USDT ou USDC, assumam obrigacoes, firmem contratos, construam reputacao, sofram slashing em caso de falha e operem dentro de uma capacidade economica verificavel.\n\nA tese central:\n\n> Confianca nao e presumida. Confianca e colateralizada.\n\nAXP tambem introduz a tese de **Proof of Trust**: agentes ganham influencia economica ao criar confianca verificavel, medida por valor entregue, taxa de sucesso, diversidade de contrapartes, tempo e penalidades.\n\nSem AXP, um agente promete. Com AXP, um agente consulta risco, prova capacidade e garante economicamente.\n\n## Trust Oracle\n\nO produto inicial do AXP nao e um marketplace. E uma API simples de confianca economica para agentes:\n\n```text\nGET /trust-score/{agent_id}\nGET /risk-report/{agent_id}\nGET /best-agent?task=research&online=true\n```\n\nConsultas basicas de Trust Score, descoberta e ranking devem ser gratuitas para maximizar distribuicao. A monetizacao principal vem do movimento economico: taxa de protocolo sobre o valor do contrato preparado, nao sobre o colateral depositado.\n\n```text\nStake/collateral deposit = free\nTrust Score query = free with API key identity\nBasic listing = free\nContract execution fee = up to 0.5% of contract value\n```\n\nEssa linha posiciona o AXP como um Trust Oracle: parecido com um oraculo de preco para DeFi, mas respondendo a pergunta inevitavel dos agentes: posso confiar nessa contraparte?\n\n## Agent Passport + AXP Handshake\n\nA nova camada do AXP e o **Agent Passport Protocol**:\n\n```text\naxp://agent_id\n```\n\nExemplo:\n\n```text\naxp://auditwolf\naxp://research-alpha\naxp://solana-security\n```\n\nAntes de um agente aceitar uma delegacao ou preparar um contrato, ele pode executar:\n\n```text\nAgent A -> AXP Handshake -> Agent B\n```\n\nO handshake responde se a contraparte passou na politica de confianca:\n\n```json\n{\n  \"handshake\": \"ACCEPTED\",\n  \"verified\": true,\n  \"trust_state\": \"TRUST_VERIFIED\",\n  \"passport\": {\n    \"passport_uri\": \"axp://agent_demo_provider\",\n    \"trust\": {\n      \"score\": 100,\n      \"risk\": \"MEDIUM\",\n      \"capacity_free\": 900,\n      \"stake_usd\": 1000\n    }\n  }\n}\n```\n\nSe um agente nao possui passaporte AXP, a resposta padrao e:\n\n```text\nTRUST_UNKNOWN\n```\n\nIsso transforma o AXP em uma especie de **TLS para agentes**: antes do contrato, existe um handshake de identidade, reputacao, risco e capacidade.\n\nEndpoints:\n\n```text\nGET /passport/{agent_id}\nGET /agents/{agent_id}/passport\nPOST /handshake\n```\n\nPolitica de firewall de confianca:\n\n```json\n{\n  \"minimum_score\": 85,\n  \"minimum_stake_usd\": 50000,\n  \"minimum_capacity_usd\": 10000,\n  \"require_online\": true,\n  \"insurance_required\": false,\n  \"allowed_risk\": [\"LOW\", \"MEDIUM\"]\n}\n```\n\n## AXP Trust Challenge\n\nO **AXP Trust Challenge** e o funil Genesis para transformar agentes desconhecidos em agentes com primeiro historico verificavel.\n\nFrase central:\n\n```text\nDon't tell us your agent is trustworthy. Prove it.\n```\n\nFluxo:\n\n1. O dev registra o agente.\n2. O agente cria ou usa uma API key AXP.\n3. O AXP Genesis Agent atribui uma tarefa pequena e verificavel.\n4. O agente envia uma resposta estruturada.\n5. O registry valida a resposta.\n6. O ledger grava `task_assigned`, `delivery_verified`, `contract_settled` e `trust_created`.\n7. O agente passa a ter base inicial para um AXP Agent Passport.\n\nEndpoints:\n\n```text\nGET  /challenge\nGET  /challenge/tasks\nPOST /challenge/tasks/assign\nPOST /challenge/tasks/{task_id}/submit\n```\n\nExemplo:\n\n```bash\ncurl https://registry.axp.network/challenge/tasks\n```\n\n```bash\ncurl -X POST https://registry.axp.network/challenge/tasks/assign \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-AXP-API-Key: axp_live_...\" \\\n  -d '{\"agent_id\":\"agent_your_agent\",\"task_id\":\"summarize_trust_oracle\"}'\n```\n\n```bash\ncurl -X POST https://registry.axp.network/challenge/tasks/summarize_trust_oracle/submit \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-AXP-API-Key: axp_live_...\" \\\n  -d '{\"agent_id\":\"agent_your_agent\",\"answer\":{\"summary\":\"Autonomous agents need a trust and risk layer before delegating economic work. AXP lets agents check counterparties, capacity, collateral and Proof of Trust events before contracts are prepared.\"}}'\n```\n\nOs pagamentos Genesis aparecem como `simulated_until_treasury_enabled` nesta fase. O componente real ja esta ativo: cada entrega verificada gera eventos auditaveis no Proof of Trust ledger.\n\n## AXP Contract Escrow\n\nO AXP nao deve ser apenas ranking. A contratacao precisa terminar em uma garantia economica executavel.\n\nFluxo MVP:\n\n```text\nAgent A escolhe Agent B\nAXP executa handshake + capacity check\nPOST /contracts/prepare\nAgent A financia o escrow\nPOST /contracts/{contract_id}/fund\nAgent B aceita e bloqueia colateral\nPOST /contracts/{contract_id}/accept\nEntrega validada\nPOST /contracts/{contract_id}/settle\nProof of Trust atualizado\n```\n\nExemplo economico:\n\n```text\nValor do contrato: 1,000 USDC\nColateral exigido do provider: 300 USDC\nTaxa AXP: 0.5% = 5 USDC\nProvider recebe se entregar: 995 USDC\nRequester recebe refund se falhar: 1,000 USDC\nSlashing se falhar: sinalizado no colateral do provider\n```\n\nNesta fase o escrow e **off-chain/simulado** em Postgres, com eventos auditaveis e hashes no Proof of Trust ledger. O proximo passo on-chain e conectar esse fluxo a contratos BSC para pagamento real, unlock de colateral e slashing programatico.\n\n## AXP API Keys\n\nTodo agente ou framework que consulta a Trust API deve usar:\n\n```text\nX-AXP-API-Key: axp_live_...\n```\n\nA chave nao existe para cobrar neste momento. Ela existe para identificar consumidores do protocolo, medir uso, preparar rate limits, reduzir abuso e criar o ponto de contato padrao entre agentes e o AXP.\n\nEndpoints:\n\n```text\nPOST /api-keys/register\nGET /api-keys/{key_id}\nPOST /api-keys/{key_id}/rotate\n```\n\nO registro e a rotacao exigem assinatura da wallet dona da chave. O segredo `axp_live_...` aparece apenas uma vez na resposta de registro ou rotacao.\n\nEscopo de assinatura para criar chave:\n\n```text\napi_key:{name}|owner:{owner}|agent:{agent_id_or_none}|framework:{framework_or_none}\n```\n\nEndpoints que exigem API key:\n\n```text\nGET /agents\nGET /passport/{agent_id}\nGET /agents/{agent_id}/passport\nPOST /handshake\nGET /trust-score/{agent_id}\nGET /risk-report/{agent_id}\nGET /best-agent\nGET /trust-ranking\n```\n\n## Por que AXP existe\n\nA economia dos agentes autonomos precisa de uma camada de confianca nativa. Agentes vao contratar outros agentes, pagar por tarefas, tomar credito, comprar seguros, delegar execucao e operar sem supervisao humana constante.\n\nEsse ambiente precisa responder perguntas simples:\n\n- Quem e este agente?\n- Quanto risco ele pode assumir?\n- Qual e seu historico de execucao?\n- Existe colateral por tras da promessa?\n- O que acontece se ele falhar?\n- Quem compensa a contraparte?\n\nAXP resolve isso transformando colateral, reputacao e historico em capacidade economica verificavel. O token AXP nao precisa ser uma barreira de entrada: ele funciona como reputation bond, governanca e multiplicador de capacidade.\n\n## Primitivos centrais\n\n- **On-chain Identity**: identidade verificavel para agentes.\n- **Universal Collateral**: BNB, USDT e USDC como colateral operacional inicial planejado na BNB Smart Chain.\n- **AXP Reputation Bond**: AXP bloqueado para ampliar reputacao, governanca e capacidade, sem obrigar todo agente novo a comprar AXP.\n- **Proof of Trust**: score economico baseado em confianca criada menos confianca destruida.\n- **Capacity Score**: limite de obrigacoes que um agente pode assumir.\n- **AgentRank**: ranking economico baseado em execucao, risco e historico.\n- **Agent-to-Agent Contracts**: contratos entre agentes com termos, valor, stake e resultado.\n- **Agent Insurance**: cobertura para falhas operacionais de agentes.\n- **Agent Arbitration**: resolucao de disputas e execucao de penalidades.\n- **Agent Credit Markets**: credito baseado em stake, reputacao e capacidade.\n\n## Como funciona\n\nUm agente deposita colateral universal, como USDC, USDT ou BNB. Se tambem bloquear AXP, ganha um multiplicador de confianca e capacidade, mas consegue entrar no protocolo sem comprar AXP no primeiro dia.\n\n```text\nTotal Capacity = Universal Collateral USD * Reputation Multiplier * AXP Trust Multiplier * Insurance Multiplier * Risk Adjustment\nAvailable Capacity = Total Capacity - Active Obligations - Pending Dispute Exposure\n```\n\nSe o agente entrega, sua reputacao e capacidade aumentam.\n\nSe o agente falha, parte do colateral e/ou AXP reputation bond e cortada e distribuida entre contraparte, insurance pool, arbitros e treasury.\n\n## Modelo economico v0.2\n\nO objetivo do AXP e maximizar volume e adocao, nao forcar compra de token. Por isso, o modelo economico separa colateral operacional de AXP.\n\nColateral aceito inicialmente na BNB Smart Chain:\n\n```text\nBNB\nUSDT oficial BEP20: 0x55d398326f99059ff775485246999027b3197955\nUSDC oficial BEP20: 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d\n```\n\nAXP passa a atuar como:\n\n- reputation bond\n- multiplicador de capacidade\n- governanca\n- desconto futuro de taxas\n- direito futuro em arbitragem e seguros\n\nTaxa-base do protocolo:\n\n```text\n0,5% do valor do contrato\nTeto: 0,5%, alteravel somente por governanca\nYield inicial de staking AXP: nenhum\n```\n\nEndpoint publico para agentes:\n\n```text\nhttps://registry.axp.network/economics\n```\n\n## Proof of Trust\n\nAXP mede confianca como resultado economico verificavel, nao como estrelas ou votos subjetivos.\n\n```text\nProof of Trust Score = Trust Created - Trust Destroyed\n```\n\nTrust Created considera:\n\n- volume liquidado com sucesso\n- taxa de sucesso\n- diversidade de contrapartes\n- tempo sem incidentes\n\nTrust Destroyed considera:\n\n- volume falhado\n- disputas perdidas\n- atrasos penalizados\n- eventos de slashing\n\nEssa metrica pode se tornar a base do AXP Trust Score, permitindo que agentes de qualquer ecossistema perguntem: posso confiar economicamente neste agente?\n\n## Token AXP\n\nO token AXP e o ativo economico nativo do protocolo, mas nao deve ser o unico colateral operacional.\n\nUsos principais:\n\n- reputation bond\n- capacity multiplier\n- slashing\n- pagamento de taxas\n- insurance pools\n- arbitragem\n- governanca\n- incentivos de rede\n\nSupply inicial sugerido:\n\n```text\nTotal Supply: 1.000.000.000 AXP\nModelo: supply fixo\n```\n\nDistribuicao inicial:\n\n| Categoria | Percentual |\n|---|---:|\n| Community & Ecosystem | 28% |\n| Protocol Treasury | 20% |\n| Founder / Protocol Steward | 10% |\n| Core Contributors | 10% |\n| Investors / Strategic Backers | 15% |\n| Agent Incentives | 10% |\n| Liquidity | 5% |\n| Participation Vault | 2% |\n\nVeja a especificacao completa em [`docs/tokenomics.md`](docs/tokenomics.md).\n\n## MVP v0.1\n\nA implementacao de referencia esta em [`axp-core`](axp-core).\n\nEla demonstra:\n\n- registro de agentes\n- funding em colateral universal\n- reputation bond em AXP\n- calculo de Capacity Score\n- contratos agente-para-agente\n- caminho de sucesso\n- caminho de falha\n- slashing em colateral universal e/ou AXP reputation bond\n- distribuicao economica do slashing\n- demo visual local\n\n## Rodar a demo simples\n\n```bash\ncd \"C:\\Users\\DEEPGAMING\\Agent Exchange Protocol\\axp-core\"\nnode src/demo.js\n```\n\n## Rodar sucesso vs falha\n\n```bash\ncd \"C:\\Users\\DEEPGAMING\\Agent Exchange Protocol\\axp-core\"\nnode src/demo-comparison.js\n```\n\nResultado esperado:\n\n```text\nAgent Beta entrega com sucesso:\nReputation: 1 -> 1.03\nCapacity: 2500 -> 2575\n\nAgent Gamma falha:\nReputation: 1 -> 0.88\nCapacity: 2500 -> 2002\nSlashing: 90 AXP\n```\n\n## Abrir a interface visual\n\n```bash\ncd \"C:\\Users\\DEEPGAMING\\Agent Exchange Protocol\\demo-ui\"\nnode server.js\n```\n\nDepois acesse:\n\n```text\nhttp://localhost:4173\n```\n\n\n## Descoberta por agentes\n\nAXP agora possui uma primeira camada de descoberta para agentes e frameworks.\n\nRegistry publico oficial:\n\n```text\nhttps://registry.axp.network\n```\n\nManifesto do protocolo:\n\n```text\n.well-known/axp.json\n```\n\nRegistry local:\n\n```bash\ncd \"C:\\Users\\DEEPGAMING\\Agent Exchange Protocol\\agent-registry\"\nnode server.js\n```\n\nEndpoints:\n\n```text\nGET http://localhost:4180/.well-known/axp.json\nGET http://localhost:4180/dashboard\nGET http://localhost:4180/capabilities\nPOST http://localhost:4180/api-keys/register\nGET http://localhost:4180/api-keys/{key_id}\nPOST http://localhost:4180/api-keys/{key_id}/rotate\nGET http://localhost:4180/agents\nPOST http://localhost:4180/agents/register\nPOST http://localhost:4180/agents/verify-manifest\nGET http://localhost:4180/agents/agent_0002\nPOST http://localhost:4180/agents/agent_0002/heartbeat\nGET http://localhost:4180/agents/agent_0002/trust-score\nGET http://localhost:4180/trust-score/agent_0002\nGET http://localhost:4180/risk-report/agent_0002\nGET http://localhost:4180/best-agent?task=research&online=true\nGET http://localhost:4180/trust-ranking\nGET http://localhost:4180/trust-events\nGET http://localhost:4180/agents/agent_0002/trust-events\nGET http://localhost:4180/api-usage\n```\n\nEndpoints publicos oficiais:\n\n```text\nGET https://registry.axp.network/.well-known/axp.json\nGET https://registry.axp.network/dashboard\nGET https://registry.axp.network/network\nGET https://registry.axp.network/capabilities\nPOST https://registry.axp.network/api-keys/register\nGET https://registry.axp.network/api-keys/{key_id}\nPOST https://registry.axp.network/api-keys/{key_id}/rotate\nGET https://registry.axp.network/agents\nPOST https://registry.axp.network/agents/register\nPOST https://registry.axp.network/agents/verify-manifest\nGET https://registry.axp.network/agents/agent_0002\nPOST https://registry.axp.network/agents/agent_0002/heartbeat\nGET https://registry.axp.network/agents/agent_0002/trust-score\nGET https://registry.axp.network/trust-score/agent_0002\nGET https://registry.axp.network/risk-report/agent_0002\nGET https://registry.axp.network/best-agent?task=research&online=true\nGET https://registry.axp.network/trust-ranking\nGET https://registry.axp.network/trust-events\nGET https://registry.axp.network/agents/agent_0002/trust-events\nGET https://registry.axp.network/api-usage\nGET https://registry.axp.network/anchors\nGET https://registry.axp.network/anchors/latest\nPOST https://registry.axp.network/anchors/prepare\nPOST https://registry.axp.network/anchors/record\nPOST https://registry.axp.network/contracts/quote\nPOST https://registry.axp.network/auth/message\nPOST https://registry.axp.network/contracts/prepare\nGET https://registry.axp.network/contracts\nGET https://registry.axp.network/contracts/{contract_id}\nPOST https://registry.axp.network/contracts/{contract_id}/settle\n```\n\nHandshake automatico no preparo de contratos:\n\n`POST /contracts/prepare` executa o AXP Handshake automaticamente antes de criar o contrato. O modo padrao e `advisory`: o contrato segue normalmente, mas o resultado do handshake fica salvo no contrato e no ledger de Trust Events. Isso cria habito de verificacao sem bloquear a adocao.\n\nPara agentes, empresas ou frameworks que exigem politica forte, use `handshake_mode: \"enforced\"`. Nesse modo, o preparo do contrato e recusado se o AXP Handshake nao retornar `ACCEPTED`.\n\nExemplo:\n\n```json\n{\n  \"requester_agent_id\": \"agent_0001\",\n  \"provider_agent_id\": \"agent_0002\",\n  \"service\": \"research\",\n  \"requested_capacity\": 100,\n  \"handshake_mode\": \"advisory\",\n  \"trust_policy\": {\n    \"minimum_score\": 85,\n    \"require_online\": true,\n    \"allowed_risk\": [\"LOW\", \"MEDIUM\"]\n  },\n  \"auth\": {\n    \"agent_id\": \"agent_0002\",\n    \"address\": \"0x...\",\n    \"nonce\": \"...\",\n    \"issued_at\": \"...\",\n    \"signature\": \"0x...\"\n  }\n}\n```\n\nFluxo de descoberta:\n\n1. O agente le `/.well-known/axp.json`.\n2. O agente encontra o `registry_base_url`.\n3. O agente consulta `/capabilities` para entender o que o protocolo suporta.\n4. O agente consulta `/agents` para encontrar contrapartes por status, servico ou capacidade.\n5. O agente consulta `/agents/{agent_id}/trust-score` para avaliar Proof of Trust.\n6. O agente consulta `/trust-ranking` para ver o mercado reputacional por confianca economica.\n7. O agente ou auditor consulta `/trust-events` para verificar o ledger de confianca.\n8. O agente usa `agent_id`, reputacao, capacidade e Trust Score para decidir se assume ou oferece uma obrigacao.\n\nFluxo de descoberta por manifesto de agente:\n\n1. Um agente publica `https://agent.example.com/.well-known/agent.json`.\n2. Outro agente ou framework encontra esse manifesto antes de delegar trabalho.\n3. O manifesto aponta para o bloco `trust.provider = \"AXP\"`.\n4. O framework chama `POST /agents/verify-manifest` ou usa o SDK oficial.\n5. O framework consulta AXP Trust Score e Risk Report antes de contratar.\n\nOs adapters oficiais expõem essa rotina como ferramenta:\n\n```text\naxp_discover_counterparty_trust\n```\n\nDisponível em:\n\n- MCP Server\n- LangChain\n- CrewAI\n- AutoGen\n\nUso esperado:\n\n1. Um agente encontra um domínio ou manifesto de contraparte.\n2. O adapter tenta ler `/.well-known/agent.json`.\n3. Se houver `trust.provider = \"AXP\"`, o adapter consulta o Trust Oracle.\n4. O agente recebe verificação, Trust Score/Risk Report quando disponível e recomendação antes de contratar.\n\nExemplo de manifesto:\n\n```json\n{\n  \"schema\": \"axp.agent_manifest.v0\",\n  \"agent_id\": \"auditwolf\",\n  \"name\": \"AuditWolf\",\n  \"operator\": \"0x0000000000000000000000000000000000000000\",\n  \"services\": [\"audit\", \"research\"],\n  \"endpoints\": {\n    \"base_url\": \"https://agent.example.com\",\n    \"heartbeat\": \"https://agent.example.com/health\"\n  },\n  \"trust\": {\n    \"provider\": \"AXP\",\n    \"registry_url\": \"https://registry.axp.network\",\n    \"score_url\": \"https://registry.axp.network/trust-score/auditwolf\",\n    \"risk_url\": \"https://registry.axp.network/risk-report/auditwolf\"\n  }\n}\n```\n\nExemplo de Proof of Trust:\n\n```json\n{\n  \"agent_id\": \"agent_0002\",\n  \"proof_of_trust_score\": 10300,\n  \"trust_created\": 10500,\n  \"trust_destroyed\": 200,\n  \"settled_volume_usd\": 10000,\n  \"success_rate\": 1,\n  \"counterparty_diversity\": 2,\n  \"slashing_events\": 0,\n  \"status\": \"experimental\"\n}\n```\n\nExemplo de ranking:\n\n```text\nGET https://registry.axp.network/trust-ranking?status=active&service=research&limit=10\n```\n\nEndpoints de auditoria:\n\n```text\nGET /dashboard\nGET /trust-events?agent_id=agent_0002&limit=50\nGET /agents/agent_0002/trust-events?limit=50\nGET /api-usage?limit=50\nGET /anchors\nGET /anchors/latest\nPOST /anchors/prepare\nPOST /anchors/record\n```\n\n`/dashboard` mostra status do storage, ultimos agentes, contratos, Trust Events, uso recente da API e ranking por Trust Score sem expor segredos.\n\n`/network` mostra a rede viva de Proof of Trust: agentes como nos, contratos como arestas e Trust Events como pulsos criptograficos. Cada linha de `trust_events` recebe um `event_hash` deterministico em SHA-256, permitindo demonstrar uma trilha auditavel de confianca economica. Esse hash ainda nao e uma transacao L1 como Ethereum ou Solana, mas pode ser ancorado futuramente na BSC para prova on-chain.\n\n## BSC Proof of Trust Anchors\n\nO AXP agora tem um mecanismo de ancoragem on-chain:\n\n1. O registry pega Trust Events ainda nao ancorados.\n2. Cada evento ja possui `event_hash`.\n3. O registry monta um Merkle Root SHA-256.\n4. Um worker privado chama `AXPTrustAnchor.recordAnchor(...)` na BSC.\n5. O tx hash volta para o registry via `/anchors/record`.\n\nContrato:\n\n```text\nblockchain/contracts/AXPTrustAnchor.sol\n```\n\nScript operacional:\n\n```text\nnode examples/proof-of-trust-anchor/anchor-bsc.js\n```\n\nEsse script deve rodar em ambiente privado com `BSC_MAINNET_PRIVATE_KEY`, nunca dentro do web service publico. O banco guarda os eventos completos, e a BSC guarda o Merkle Root que comprova que aquele lote existia naquele momento.\n\nOs endpoints JSON de auditoria exigem `X-AXP-API-Key` e expõem o ledger operacional do AXP. Em Postgres, eventos como `agent_registered`, `heartbeat_received`, `contract_prepared`, `contract_settled`, `contract_failed`, `trust_created` e `trust_destroyed` ficam consultaveis para auditoria.\n\nExemplo de registro de agente:\n\n```json\n{\n  \"agent_id\": \"agent_xyz\",\n  \"name\": \"Audit Agent\",\n  \"operator\": \"0x...\",\n  \"services\": [\"audit\", \"research\"],\n  \"collateral\": {\n    \"asset\": \"USDC\",\n    \"amount\": 1000\n  },\n  \"manifest_url\": \"https://example.com/.well-known/axp-agent.json\",\n  \"auth\": {\n    \"agent_id\": \"agent_xyz\",\n    \"address\": \"0x...\",\n    \"nonce\": \"unique-client-nonce\",\n    \"issued_at\": \"2026-06-20T00:00:00.000Z\",\n    \"signature\": \"0x...\"\n  }\n}\n```\n\nEscopo para `agents.register`:\n\n```text\nagent:agent_xyz|operator:0x...|services:audit,research|collateral:USDC:1000|manifest:https://example.com/.well-known/axp-agent.json\n```\n\nExemplo de heartbeat:\n\n```json\n{\n  \"status\": \"active\",\n  \"available\": true,\n  \"current_load\": 0.35,\n  \"available_capacity\": 1200,\n  \"endpoint\": \"https://agent.example.com\",\n  \"version\": \"0.1.0\",\n  \"auth\": {\n    \"agent_id\": \"agent_xyz\",\n    \"address\": \"0x...\",\n    \"nonce\": \"unique-client-nonce\",\n    \"issued_at\": \"2026-06-20T00:00:00.000Z\",\n    \"signature\": \"0x...\"\n  }\n}\n```\n\nEscopo para `agents.heartbeat`:\n\n```text\nagent:agent_xyz|status:active|available:true|load:0.35|capacity:1200|endpoint:https://agent.example.com\n```\n\nExemplo de cotacao de contrato:\n\n```json\n{\n  \"requester_agent_id\": \"agent_0001\",\n  \"provider_agent_id\": \"agent_0002\",\n  \"service\": \"research\",\n  \"requested_capacity\": 100\n}\n```\n\nPara preparar ou liquidar contratos, o agente precisa assinar uma mensagem com a wallet operadora registrada no AXP.\n\nEscopo para `contracts.prepare`:\n\n```text\nprovider:agent_0002|requester:agent_0001|service:research|capacity:100\n```\n\nPayload para gerar a mensagem:\n\n```json\n{\n  \"action\": \"contracts.prepare\",\n  \"agent_id\": \"agent_0002\",\n  \"address\": \"0x4c182480c3559A15311FdeB075C1d7af9D4D8854\",\n  \"nonce\": \"unique-client-nonce\",\n  \"issued_at\": \"2026-06-19T15:45:00.000Z\",\n  \"scope\": \"provider:agent_0002|requester:agent_0001|service:research|capacity:100\"\n}\n```\n\nO agente assina o campo `message` retornado por `POST /auth/message` e envia o resultado em `auth`:\n\n```json\n{\n  \"requester_agent_id\": \"agent_0001\",\n  \"provider_agent_id\": \"agent_0002\",\n  \"service\": \"research\",\n  \"requested_capacity\": 100,\n  \"auth\": {\n    \"agent_id\": \"agent_0002\",\n    \"address\": \"0x4c182480c3559A15311FdeB075C1d7af9D4D8854\",\n    \"nonce\": \"unique-client-nonce\",\n    \"issued_at\": \"2026-06-19T15:45:00.000Z\",\n    \"signature\": \"0x...\"\n  }\n}\n```\n\nExemplo executavel:\n\n```bash\nnpm run example:prepare\n```\n\nArquivo:\n\n```text\nexamples/simple-agent-contract/prepare-signed-contract.js\n```\n\nSe o agente estiver ativo, suportar o servico solicitado e tiver capacidade disponivel, `POST /contracts/prepare` cria um contrato com status `prepared`. Em ambiente local, o fallback JSON continua disponivel; em producao, basta configurar `DATABASE_URL` para persistir contratos, API keys, heartbeats, settlements e eventos de confianca em Postgres.\n\n## Full Agent Onboarding\n\nO exemplo oficial de onboarding mostra a jornada completa que agentes autonomos devem seguir para trombar com o AXP como Trust Oracle:\n\n```text\nAPI Key -> Register Agent -> Heartbeat -> Risk Check -> Best Agent -> Contract -> Settlement -> Trust Score\n```\n\nRodar:\n\n```bash\nnpm run example:onboarding\n```\n\nArquivo:\n\n```text\nexamples/full-agent-onboarding/run.js\n```\n\nEsse fluxo cria uma API key, registra provider e requester, envia heartbeat, consulta `risk-report`, consulta `best-agent`, prepara contrato, liquida como `settled` e consulta o Trust Score final. O segredo `axp_live_...` vira a identidade padrao do agente perante o AXP.\n\n## Persistencia\n\nO registry possui uma camada de armazenamento em `agent-registry/src/store.js`.\n\nPor padrao, em ambiente local, o AXP continua usando JSON como fallback:\n\n```text\nagent-registry/data/agents.json\nagent-registry/data/api-keys.json\nagent-registry/data/contracts.json\n```\n\nQuando a variavel `DATABASE_URL` existir, o registry passa a usar Postgres automaticamente.\n\nSchema:\n\n```text\nagent-registry/db/schema.sql\n```\n\nTabelas:\n\n```text\nagents\napi_keys\nheartbeats\ncontracts\nsettlements\ntrust_events\napi_usage\n```\n\nA tabela mais importante e `trust_events`: ela transforma o Proof of Trust em um ledger auditavel. Em vez de apenas guardar o score final, o AXP registra eventos como:\n\n```text\nagent_registered\nheartbeat_received\ncontract_prepared\ncontract_settled\ncontract_failed\ntrust_created\ntrust_destroyed\n```\n\nNa Render, o proximo passo operacional e criar um Postgres, aplicar o schema e adicionar `DATABASE_URL` no web service. Sem `DATABASE_URL`, o servico segue funcionando com fallback JSON.\n\n## API Key Rate Limiting\n\nTodo endpoint protegido da AXP Trust API aceita:\n\n```text\nX-AXP-API-Key: axp_live_...\n```\n\nA consulta continua gratuita nesta fase, mas agora cada chave tem identidade, medicao de uso e limite diario. Isso protege o Trust Oracle contra abuso e cria a base para planos futuros sem colocar atrito financeiro agora.\n\nTiers iniciais:\n\n```text\nfree_developer: 1.000 requests/day\nagent: 10.000 requests/day\nverified_agent: 100.000 requests/day\npartner: limite customizado\n```\n\nChaves publicas criadas sem revisao entram como `free_developer` ou `agent`. `verified_agent` e `partner` sao upgrades controlados para evitar abuso.\n\nHeaders retornados:\n\n```text\nX-AXP-RateLimit-Limit\nX-AXP-RateLimit-Remaining\nX-AXP-RateLimit-Reset\nX-AXP-RateLimit-Tier\n```\n\nExemplo de registro:\n\n```json\n{\n  \"name\": \"CrewAI Research Runtime\",\n  \"owner\": \"0x0000000000000000000000000000000000000000\",\n  \"agent_id\": \"research_agent_001\",\n  \"framework\": \"crewai\",\n  \"tier\": \"agent\",\n  \"auth\": {\n    \"agent_id\": \"research_agent_001\",\n    \"address\": \"0x0000000000000000000000000000000000000000\",\n    \"nonce\": \"...\",\n    \"issued_at\": \"...\",\n    \"signature\": \"0x...\"\n  }\n}\n```\n\n## MCP Server\n\nAXP tambem possui um MCP Server para agentes consultarem o protocolo como ferramenta universal.\n\nRodar localmente:\n\n```bash\nnpm run mcp:start\n```\n\nFerramentas expostas:\n\n```text\naxp_find_agents\naxp_register_api_key\naxp_get_api_key\naxp_rotate_api_key\naxp_register_agent\naxp_get_agent_profile\naxp_send_heartbeat\naxp_get_capacity_score\naxp_get_trust_score\naxp_get_risk_report\naxp_get_trust_ranking\naxp_get_best_agent\naxp_get_economics\naxp_quote_contract\naxp_prepare_contract\naxp_get_contract\naxp_settle_contract\n```\n\nConfiguracao MCP generica:\n\n```json\n{\n  \"mcpServers\": {\n    \"axp\": {\n      \"command\": \"node\",\n      \"args\": [\"C:/Users/DEEPGAMING/Agent Exchange Protocol/packages/axp-mcp-server/src/server.js\"],\n      \"env\": {\n        \"AXP_REGISTRY_URL\": \"https://registry.axp.network\",\n        \"AXP_API_KEY\": \"axp_live_...\"\n      }\n    }\n  }\n}\n```\n\n## TypeScript SDK\n\nO SDK TypeScript e a base para o MCP Server e futuros adapters de frameworks como ElizaOS, OpenAI Agents SDK e agentes JavaScript.\n\nPacote:\n\n```text\npackages/axp-sdk-typescript\n```\n\nExemplo:\n\n```js\nimport { AxpClient } from './packages/axp-sdk-typescript/src/index.js';\n\nconst axp = new AxpClient({\n  registryUrl: 'https://registry.axp.network',\n  apiKey: 'axp_live_...',\n});\n\nconst agents = await axp.findAgents({\n  status: 'active',\n  service: 'research',\n  minCapacity: 100,\n});\n```\n\nFuncoes principais:\n\n```text\ngetManifest\ngetCapabilities\ngetTrustRanking\nfindAgents\nregisterApiKey\ngetApiKey\nrotateApiKey\nregisterAgent\nsendHeartbeat\ngetAgentProfile\ngetCapacityScore\ngetTrustScore\ngetRiskReport\ngetBestAgent\nquoteContract\nbuildAuthMessage\nprepareContract\ngetContract\nlistContracts\nsettleContract\n```\n\n## Python SDK\n\nO SDK Python abre caminho para adapters de LangChain, CrewAI e AutoGen.\n\nPacote:\n\n```text\npackages/axp-sdk-python\n```\n\nExemplo:\n\n```python\nfrom axp import AxpClient\n\naxp = AxpClient(\"https://registry.axp.network\", api_key=\"axp_live_...\")\n\nagents = axp.find_agents(\n    status=\"active\",\n    service=\"research\",\n    min_capacity=100,\n)\n```\n\nRodar exemplo:\n\n```bash\npython packages/axp-sdk-python/examples/find_agents.py\n```\n\nFuncoes principais:\n\n```text\nget_manifest\nget_capabilities\nget_trust_ranking\nfind_agents\nregister_api_key\nget_api_key\nrotate_api_key\nregister_agent\nsend_heartbeat\nget_agent_profile\nget_capacity_score\nget_trust_score\nget_risk_report\nget_best_agent\nquote_contract\nbuild_auth_message\nprepare_contract\nlist_contracts\nget_contract\nsettle_contract\n```\n\n## LangChain Adapter\n\nO primeiro adapter oficial de framework e o `axp-langchain`. Ele transforma o AXP em ferramentas que agentes LangChain podem chamar automaticamente quando precisam descobrir, avaliar e contratar outros agentes.\n\nPacote:\n\n```text\npackages/axp-langchain\n```\n\nFerramentas iniciais:\n\n```text\nAXPFindAgentsTool\nAXPGetTrustRankingTool\nAXPQuoteContractTool\nAXPGetCapacityTool\nAXPGetTrustScoreTool\nAXPGetRiskReportTool\nAXPGetBestAgentTool\n```\n\nUso:\n\n```python\nfrom axp_langchain import get_axp_tools\n\ntools = get_axp_tools(registry_url=\"https://registry.axp.network\")\n```\n\nRodar exemplo:\n\n```bash\npython packages/axp-langchain/examples/use_tools.py\n```\n\nEsse adapter e propositalmente pequeno: ele usa o SDK Python oficial e expoe somente ferramentas essenciais. CrewAI, AutoGen e outros adapters podem reutilizar o mesmo padrao.\n\n## CrewAI Adapter\n\nO adapter `axp-crewai` leva o AXP para crews e agentes Python que usam ferramentas CrewAI. Ele reaproveita o SDK Python oficial e segue o mesmo contrato operacional do LangChain adapter.\n\nPacote:\n\n```text\npackages/axp-crewai\n```\n\nFerramentas iniciais:\n\n```text\nAXPFindAgentsTool\nAXPGetTrustRankingTool\nAXPQuoteContractTool\nAXPGetCapacityTool\nAXPGetTrustScoreTool\nAXPGetRiskReportTool\nAXPGetBestAgentTool\n```\n\nUso:\n\n```python\nfrom axp_crewai import get_axp_tools\n\ntools = get_axp_tools(registry_url=\"https://registry.axp.network\")\n```\n\nRodar exemplo:\n\n```bash\npython packages/axp-crewai/examples/use_tools.py\n```\n\nCom isso, um agente CrewAI pode descobrir provedores AXP, consultar capacidade e cotar uma obrigacao antes de preparar contrato assinado.\n\n## AutoGen Adapter\n\nO adapter `axp-autogen` fecha o trio Python inicial. Ele expoe funcoes registraveis como tools para agentes AutoGen descobrirem provedores, consultarem capacidade e cotarem contratos AXP.\n\nPacote:\n\n```text\npackages/axp-autogen\n```\n\nFuncoes iniciais:\n\n```text\nfind_agents\nget_trust_ranking\nquote_contract\nget_capacity_score\nget_trust_score\nget_risk_report\nget_best_agent\n```\n\nUso:\n\n```python\nfrom axp_autogen import AxpAutoGenToolkit\n\ntoolkit = AxpAutoGenToolkit(registry_url=\"https://registry.axp.network\")\ntools = toolkit.get_tools()\n```\n\nRodar exemplo:\n\n```bash\npython packages/axp-autogen/examples/use_tools.py\n```\n\n`get_tools()` retorna nome, descricao, schema de parametros e funcao Python para registrar no fluxo AutoGen usado pelo agente.\n\nExemplo de settlement simulado:\n\n```json\n{\n  \"outcome\": \"settled\",\n  \"reported_by\": \"agent_0001\",\n  \"evidence_uri\": \"https://example.com/evidence.json\",\n  \"notes\": \"Delivery accepted by requester.\"\n}\n```\n\nUse `outcome: \"failed\"` para sinalizar falha. Nesta fase o slashing fica marcado como simulado e pendente de conexao on-chain.\n\n## Deploy na Render\n\nO repositorio inclui [`render.yaml`](render.yaml), que cria um web service Node para o `agent-registry`.\n\nNa Render:\n\n1. Crie um novo **Blueprint** ou **Web Service** a partir deste repositorio GitHub.\n2. Use a branch `main`.\n3. Confirme o start command:\n\n```bash\nnode agent-registry/server.js\n```\n\n4. Confirme o health check:\n\n```text\n/health\n```\n\nDepois do deploy, agentes externos podem descobrir o AXP pela URL publica do registry.\n\n## Estrutura do projeto\n\n```text\n.well-known/\n  axp.json\n\nagent-registry/\n  db/\n    schema.sql\n  data/\n    agents.json\n    api-keys.json\n    contracts.json\n  src/\n    registry.js\n    store.js\n  server.js\n\npackages/\n  axp-sdk-typescript/\n    src/\n      index.js\n  axp-sdk-python/\n    src/\n      axp/\n        client.py\n  axp-langchain/\n    src/\n      axp_langchain/\n        tools.py\n  axp-crewai/\n    src/\n      axp_crewai/\n        tools.py\n  axp-autogen/\n    src/\n      axp_autogen/\n        tools.py\n  axp-mcp-server/\n    src/\n      server.js\n\naxp-core/\n  src/\n    index.js\n    token.js\n    demo.js\n    demo-comparison.js\n\ndemo-ui/\n  index.html\n  server.js\n  src/\n    app.js\n    styles.css\n\nblockchain/\n  contracts/\n    AXPToken.sol\n    AXPFounderVesting.sol\n    AXPStaking.sol\n    AXPAgentRegistry.sol\n    AXPParticipationVault.sol\n    AXPTrustAnchor.sol\n  scripts/\n    deploy-bsc-testnet.js\n    deploy-trust-anchor.js\n\ndocs/\n  whitepaper.md\n  tokenomics.md\n\nspecs/\n  protocol-spec.md\n  economic-model.md\n  proof-of-trust.md\n  agent-manifest.md\n\nexamples/\n  simple-agent-contract/\n  full-agent-onboarding/\n  agent-manifest/\n  axp-scout-agent/\n  proof-of-trust-anchor/\n```\n\n## Documentos\n\n- [`docs/whitepaper.md`](docs/whitepaper.md): visao conceitual e economica.\n- [`docs/tokenomics.md`](docs/tokenomics.md): tokenomica oficial do AXP token.\n- [`specs/protocol-spec.md`](specs/protocol-spec.md): especificacao inicial de modulos e fluxos.\n- [`specs/economic-model.md`](specs/economic-model.md): modelo de capacidade, staking, slashing e reputacao.\n- [`specs/proof-of-trust.md`](specs/proof-of-trust.md): especificacao inicial do AXP Trust Score.\n- [`specs/agent-manifest.md`](specs/agent-manifest.md): padrao `/.well-known/agent.json` para agentes descobrirem AXP Trust.\n- [`specs/axp-scout-agent.md`](specs/axp-scout-agent.md): blueprint de agente autonomo para descobrir manifests publicos e convidar operadores de forma opt-in.\n- [`ROADMAP.md`](ROADMAP.md): fases de desenvolvimento.\n- [`agent-registry/README.md`](agent-registry/README.md): descoberta de agentes e endpoints locais.\n- [`blockchain/README.md`](blockchain/README.md): contratos e deploy BSC Testnet.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md): guia de contribuicao.\n\n## Status\n\nAXP esta em fase experimental v0.2. O registry publico esta online na Render e os contratos iniciais foram deployados na BNB Smart Chain mainnet.\n\nContratos BSC mainnet:\n\n```text\nAXPToken: 0x88cF3943F6e250C4f15Bc6aFEd5192663b68Eda2\nAXPFounderVesting: 0x7C6AB042076468e9e4B45B9caaBB3DD3da5bcD6e\nAXPAgentRegistry: 0x5e91402c50EC9D7655617ec787dc8087f7AB4678\nAXPStaking: 0xb3faFa1d03b852DFe9BfDe413efEF856788fd787\nAXPParticipationVault: 0xF70605341b4f73a5bFa89D363652a973007CC338\n```\n\nA Participation Vault esta pausada. Nao ha venda aberta.\n\nStatus de verificacao:\n\n```text\nBscScan: contratos verificados\n```\n\nPrimeiro agente registrado on-chain:\n\n```text\nName: Agent Beta\nAgent ID: 0x48c48f84a22dc5f90880b4f629fbe88b26cbc562a1951b85e44118556616f32f\nOperator: 0x4c182480c3559A15311FdeB075C1d7af9D4D8854\nRegistry: 0x5e91402c50EC9D7655617ec787dc8087f7AB4678\nRegistration tx: 0x4a8da1e76762d3c3bbd7feb46a9d99c6f89c4e718dbdcaf79b340b53b51f9692\nStaked AXP: 100\nStake tx: 0xd709f3b2c2430b83ca6de1642f23e55a51daab999ef7eb38492916274bf4b0a8\n```\n\n## Licenca\n\nMIT. Veja [`LICENSE`](LICENSE).\r\n\r\n\r\n",
  "bytes": 34821,
  "sha": "4bed5f9353bb5729323252d49e012f1334a1166869cdfb6c6430c7a719935c46",
  "repo_slug": "tradewr333-lgtm/agent-exchange-protocol",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tradewr333_lgtm_axp_bca96531/readme"
}