Billetera y depósitos

• En el entorno de práctica hay una billetera por dueño, con dinero de práctica. GET /v1/wallets la lista y GET /v1/wallets/{wallet_id} la consulta.
• balance.available es lo que se puede usar ya. balance.pending son depósitos que llegaron y todavía no se acreditan.
• controls dice quién puede firmar. Exportar la clave no existe en la API.
• Son rutas del dueño, y solo leen: la llave de un agente no ve billeteras ni depósitos, y ninguna ruta mueve dinero hacia adentro ni hacia afuera.

GET /v1/deposit-instructions devuelve la dirección, la red y el mínimo. No existe POST /v1/deposits: el dinero llega y el sistema lo detecta. Hoy solo hay USDC en la red Base, y en práctica la dirección no recibe dinero 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"}

La lista de estados es abierta: tu código debe tolerar un estado nuevo. Cada cambio de estado emite un evento funding.*.

Cómo avanza

Estos son todos los pasos posibles. Un estado final no tiene salida.

• creación → 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 crea un depósito de práctica y suma el dinero a la billetera. Con una llave real responde 404. Si mandas Idempotency-Key, repetir la petición devuelve el mismo 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"  }}

Montos con una rama

Estos montos de prueba llevan el depósito por un camino especial. La espera corre con el reloj de práctica: adelántalo con POST /v1/test/clock/advance.

• Mínimo 1.00 USDC: un monto menor no se acredita.
• Hasta 10000.00 por depósito.
• Hasta 20000.00 y 30 depósitos por día.
• Pasado un tope, la respuesta es 422 quota_exceeded.

Cada paso emite un evento para el servidor del dueño, en este orden. El detalle de la entrega está en Eventos y webhooks.

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