luniumpay-com Mesh · Economy API

openapi: 3.2.0
info:
  title: Luniumpay Com Mesh · Economy 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 · Economy 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 · Economy
  description: 0,10 % sobre volume liquidado de quem voce trouxe. Nada por cadastro.
paths:
  /mesh/economy:
    get:
      tags:
      - Mesh · Economy
      operationId: meshEconomy
      summary: Regras publicas da economia da rede
      description: 0,10 % sobre volume LIQUIDADO de quem voce trouxe, somente nivel 1. Cadastro, indicacao, cotacao e sandbox nao pagam nada.
      security: []
      x-lunium-agent-safe: true
      responses:
        '200':
          description: A politica vigente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshEconomyPolicy'
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /mesh/agents/{agent_id}/rewards:
    get:
      tags:
      - Mesh · Economy
      operationId: meshAgentRewards
      summary: Saldo de recompensas e extrato do ledger
      security: []
      x-lunium-agent-safe: true
      x-lunium-reward-eligible: true
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
        example: agt_2319c9da313e84af3b
      responses:
        '200':
          description: Saldo e ledger.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardBalance'
        '404':
          description: Nao existe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAutocorrigivel'
    servers:
    - url: https://api.luniumpay.com
      description: Produção
components:
  schemas:
    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
    RewardEvent:
      type: object
      description: 'Lancamento do ledger. Imutavel: estorno e um lancamento NEGATIVO novo, nunca UPDATE nem DELETE.'
      properties:
        transaction_id:
          type: string
        transaction_kind:
          type: string
          enum:
          - cashout
          - cashin
        source_agent_id:
          type: string
          description: Quem gerou o volume.
        referral_level:
          type: integer
          example: 1
        volume_cents:
          type: integer
        rate_bps:
          type: integer
          example: 10
        gross_reward_cents:
          type: integer
        revenue_cents:
          type: integer
          description: Receita da Lunium na operacao.
        revenue_cap_cents:
          type: integer
          description: Teto aplicavel a recompensa.
        final_reward_cents:
          type: integer
          description: Negativo quando e estorno.
        reward_usdt:
          type:
          - number
          - 'null'
        status:
          type: string
          enum:
          - pending
          - available
          - paid
          - reversed
        motivo:
          type:
          - string
          - 'null'
        criado_em:
          type: string
          format: date-time
    MeshEconomyPolicy:
      type: object
      description: Regras publicas da economia. NO SETTLEMENT → NO REWARD.
      properties:
        model:
          type: string
          example: transaction_attribution
        direct_rate:
          type: string
          example: 0.10%
        direct_rate_bps:
          type: integer
          example: 10
        max_paid_levels:
          type: integer
          example: 1
        recruitment_reward:
          type: boolean
          example: false
        requires_settled_transaction:
          type: boolean
          example: true
        revenue_share_cap:
          type: string
    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
    RewardBalance:
      type: object
      description: Saldo do agent_id — nunca da credencial. Rotacionar chave nao perde saldo.
      properties:
        agent_id:
          type: string
        own_volume_cents:
          type: integer
        direct_referral_volume_cents:
          type: integer
        network_volume_cents:
          type: integer
        pending_rewards_cents:
          type: integer
        available_rewards_cents:
          type: integer
        paid_rewards_cents:
          type: integer
        lifetime_rewards_cents:
          type: integer
        reward_events:
          type: integer
        reversals:
          type: integer
        policy:
          $ref: '#/components/schemas/MeshEconomyPolicy'
        ledger:
          type: array
          items:
            $ref: '#/components/schemas/RewardEvent'
  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