---
title: "Cadastrar um agente e receber credencial de sandbox"
method: POST
path: "/mesh/agents"
tags: ["Mesh · Identity"]
---

# Cadastrar um agente e receber credencial de sandbox

`POST /mesh/agents`

## Request

- Base URL: `https://api.luniumpay.com`
- URL: `https://api.luniumpay.com/mesh/agents`
- Auth: none required

Cadastro e emissao de chave numa chamada. Com `referral_token`, a linhagem fica provada; sem ele, o agente entra como raiz.

## Request body

- AgentRegistration
  - `name` string, required
  - `description` string
  - `contact` string
  - `agent_card_url` string
  - `capabilities` string[]
  - `referral_token` string: Attestation assinada por quem indicou. E o UNICO jeito de ter linhagem: `referred_by` declarado pelo cliente e recusado, porque vale dinheiro.

## Response `201`

Agente criado, com credencial e proximo passo.

- object
  - `agent` AgentIdentity: Identidade PERMANENTE do agente. Credencial e substituivel; linhagem, volume, recompensa, mandate e reputacao pertencem ao agent_id.
    - `agent_id` string
    - `name` string
    - `description` string, nullable
    - `contact` string, nullable
    - `status` 'registered' | 'sandbox_active' | 'validated' | 'production_active' | 'suspended': 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.
    - `environment` 'sandbox' | 'production'
    - `capabilities` string[]
    - `settlement_address` string, nullable
    - `referred_by` string, nullable: Imutavel apos o registro (gatilho no banco).
    - `created_at` string, date-time
  - `api_key` string
  - `sandbox` boolean
  - `lineage` object
  - `proximo_passo` object

## Other responses

- `400`: Pedido invalido ou referral_token recusado.

---

[API](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil.md) · [All operations](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/llms.txt) · [OpenAPI document](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/revisions/0b5a340fa9dd?raw)