luniumpay-com Mesh · Network API

openapi: 3.2.0
info:
  title: Luniumpay Com Mesh · Network API
  version: 1.48.0
  contact:
    name: Lunium
    email: contato@luniumpay.com
    url: https://luniumpay.com/integrar?utm_source=openapi&utm_medium=spec
  x-documentation-revision: 2026-09-17.4
  x-lunium-partners:
    name: Lunium Partners — comunidade oficial de integradores
    url: https://t.me/+FerOZMRRP_g5MDk5
    description: Avisos operacionais, mudanças de contrato e troca entre parceiros. Nunca publique uma chave de API no grupo.
  description: 'Operations tagged Mesh · Network across 2 of this provider''s published API definitions: api.json, luniumpay-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.luniumpay.com
  description: Produção
security:
- ApiKey: []
tags:
- name: Mesh · Network
  description: Linhagem provada, grafo de indicacoes e volume de rede.
paths:
  /mesh/agents:
    get:
      tags:
      - Mesh · Network
      operationId: meshListAgents
      summary: Quem esta na rede
      security: []
      x-lunium-agent-safe: true
      description: Diretorio publico. Nunca devolve chave, hash nem token.
      responses:
        '200':
          description: Agentes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentIdentity'
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /mesh/referrals:
    post:
      tags:
      - Mesh · Network
      operationId: meshIssueReferral
      summary: Emitir uma attestation de indicacao
      description: Exige a X-API-Key do agente que indica. Devolve token assinado, de uso unico e com prazo. E o unico jeito de a linhagem existir — e, com ela, os 0,10 %.
      x-lunium-agent-safe: true
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                capability:
                  type: string
                expires_in_minutes:
                  type: integer
                  default: 60
                  maximum: 10080
      responses:
        '201':
          description: Attestation emitida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralAttestation'
        '401':
          description: Sem chave.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAutocorrigivel'
        '404':
          description: Chave nao associada a um agente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAutocorrigivel'
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /mesh/agents/{agent_id}/network:
    get:
      tags:
      - Mesh · Network
      operationId: meshAgentNetwork
      summary: Linhagem, arvore e volume de rede
      security: []
      x-lunium-agent-safe: true
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
        example: agt_2319c9da313e84af3b
      description: Consulta recursiva no banco. `network_volume` conta a arvore inteira; `reward_eligible_volume` conta so o que remunera (nivel 1).
      responses:
        '200':
          description: A rede.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetwork'
        '404':
          description: Nao existe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAutocorrigivel'
    servers:
    - url: https://api.luniumpay.com
      description: Produção
components:
  schemas:
    AgentLifecycle:
      type: string
      enum:
      - registered
      - sandbox_active
      - validated
      - production_active
      - suspended
      description: 'Producao e ativada por POLITICA, sem humano no circuito. Nao existe estado de espera por aprovacao: o controle de risco esta na regua por PAGADOR (cash-in), no teto por operacao, no teto diario de quem recebe o PIX (venda) e no mandate da propria chave — nao existe teto diario por chave de API (desde 10/09/2026), nem fila de aprovacao.'
    NextAction:
      type: object
      description: O proximo passo, em forma de chamada. Um agente nunca deveria precisar interpretar texto humano para continuar.
      properties:
        method:
          type: string
          example: POST
        endpoint:
          type: string
          example: /mesh/agents/{agent_id}/settlement
        why:
          type: string
          example: sem rota de liquidacao o dinheiro nao tem para onde ir
    AgentNetwork:
      type: object
      description: A arvore abaixo de um agente. `network_volume` conta a arvore inteira (serve para reputacao); `reward_eligible_volume` conta so o que remunera.
      properties:
        agent_id:
          type: string
        referred_by:
          type:
          - string
          - 'null'
        depth:
          type: integer
        direct_children:
          type: integer
        total_descendants:
          type: integer
        own_volume_cents:
          type: integer
        own_transactions:
          type: integer
        network_volume_cents:
          type: integer
        network_transactions:
          type: integer
        reward_eligible_volume_cents:
          type: integer
        lifetime_rewards_cents:
          type: integer
        first_operation:
          type:
          - string
          - 'null'
          format: date-time
        production_since:
          type:
          - string
          - 'null'
          format: date-time
        children:
          type: array
          items:
            type: object
    AgentIdentity:
      type: object
      description: Identidade PERMANENTE do agente. Credencial e substituivel; linhagem, volume, recompensa, mandate e reputacao pertencem ao agent_id.
      properties:
        agent_id:
          type: string
          example: agt_2319c9da313e84af3b
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        contact:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/AgentLifecycle'
        environment:
          type: string
          enum:
          - sandbox
          - production
        capabilities:
          type: array
          items:
            type: string
        settlement_address:
          type:
          - string
          - 'null'
        referred_by:
          type:
          - string
          - 'null'
          description: Imutavel apos o registro (gatilho no banco).
        created_at:
          type: string
          format: date-time
    ReferralAttestation:
      type: object
      description: Token assinado (JWS HS256) que PROVA quem indicou. Uso unico, com prazo. Sem ele o agente entra como raiz e ninguem recebe por ele.
      properties:
        type:
          type: string
          example: mesh_referral
        referrer_agent_id:
          type: string
        referral_token:
          type: string
        capability:
          type:
          - string
          - 'null'
        nonce:
          type: string
        expires_at:
          type: string
          format: date-time
        one_time_use:
          type: boolean
          example: true
    ErroAutocorrigivel:
      type: object
      description: 'Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).'
      properties:
        erro:
          type: string
          example: mandate_valor_acima_do_teto
        acao:
          type: string
          enum:
          - corrigir
          - esperar
          - parar
          - repetir
        detail:
          type: string
        missing:
          type: array
          items:
            type: string
        next_actions:
          type: array
          items:
            $ref: '#/components/schemas/NextAction'
      required:
      - erro
      - acao
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Chave criada em `POST /keys`. Aparece uma única vez — guarde no momento da criação.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your key. `lun_test_…` is sandbox (moves nothing); `lun_…` is production.
externalDocs:
  description: Mínimos e máximos por moeda e rede
  url: https://docs.luniumpay.com/minimos
x-refined-from:
- api.json
- luniumpay-com-openapi.json