Carteira e depósitos

• No ambiente de prática há uma carteira por dono, com dinheiro de prática. GET /v1/wallets a lista e GET /v1/wallets/{wallet_id} a consulta.
• balance.available é o que já se pode usar. balance.pending são depósitos que chegaram e ainda não foram creditados.
• controls diz quem pode assinar. Exportar a chave não existe na API.
• São rotas do dono, e só leem: a chave de um agente não vê carteiras nem depósitos, e nenhuma rota move dinheiro para dentro nem para fora.

GET /v1/deposit-instructions devolve o endereço, a rede e o mínimo. Não existe POST /v1/deposits: o dinheiro chega e o sistema o detecta. Hoje só há USDC na rede Base, e em prática o endereço não recebe dinheiro real.

curl https://api.nouronpass.com/v1/deposit-instructions \
  -H "Authorization: Bearer $NOURON_OWNER_KEY"

{  "object": "deposit_instruction",  "method": "usdc_onchain",  "chain": "base",  "address": "0x1f2e3d4c5b6a79880a1b2c3d4e5f60718293a4b5",  "wallet_id": "wal_3c4d5e6f708192a3b4c5d6e7f8091a2b",  "minimum_amount": "1.00",  "confirmations_required": 12,  "notice": "Dinero de práctica: esta dirección es del entorno de prueba y no recibe dinero real.",  "request_id": "req_2c6d9wLx"}

A lista de estados é aberta: seu código deve tolerar um estado novo. Cada mudança de estado emite um evento funding.*.

Como avança

Estes são todos os passos possíveis. Um estado final não tem saída.

• criação → awaiting_deposit
• awaiting_deposit → received
• awaiting_deposit → failed
• received → converted
• received → under_review
• received → returned
• received → failed
• under_review → converted
• under_review → returned
• under_review → failed

POST /v1/test/fund cria um depósito de prática e soma o dinheiro à carteira. Com uma chave real responde 404. Se você mandar Idempotency-Key, repetir a requisição devolve o mesmo depósito.

curl -X POST https://api.nouronpass.com/v1/test/fund \
  -H "Authorization: Bearer $NOURON_OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"25.00"}'

{  "object": "test_funding",  "amount": "25.00",  "balance_after": "1025.00",  "deposit": {    "id": "dep_9a1b2c3d4e5f60718293a4b5c6d7e8f9",    "object": "deposit",    "livemode": false,    "status": "converted",    "method": "test",    "amount": "25.50",    "amount_credited": "25.50",    "fee": "0.00",    "currency": "usdc",    "wallet_id": "wal_3c4d5e6f708192a3b4c5d6e7f8091a2b",    "source": {      "chain": "base",      "tx_hash": "0x5f1d3b8a2c4e6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",      "from_address": "0x7a9c1e3b5d7f9021a3b5c7d9e1f30415a6b7c8d9"    },    "failure": null,    "created_at": "2026-10-13T14:03:21.114Z",    "received_at": "2026-10-13T14:03:21.114Z",    "credited_at": "2026-10-13T14:03:21.114Z",    "request_id": "req_4k8m2pQ7"  }}

Valores com um ramo

Estes valores de teste levam o depósito por um caminho especial. A espera corre com o relógio de prática: adiante-o com POST /v1/test/clock/advance.

• Mínimo 1.00 USDC: um valor menor não é creditado.
• Até 10000.00 por depósito.
• Até 20000.00 e 30 depósitos por dia.
• Passado um limite, a resposta é 422 quota_exceeded.

Cada passo emite um evento para o servidor do dono, nesta ordem. O detalhe da entrega está em Eventos e webhooks.

• funding.awaiting_deposit
• funding.deposit_received
• funding.failed
• funding.converted
• funding.under_review
• funding.returned