nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: sync from backend a4d72df - cap confirmation floors

Browse Source
This commit is contained in:
Siavash Sameni
2026-05-31 15:21:28 +04:00
parent 798fa2f48e
commit 9f8cc104c7
9 changed files with 48 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
03 - API Reference/Scanner API.md
View File

@@ -41,7 +41,7 @@ Register a new payment intent. The scanner will watch the specified chain for a
| `amount` | string | yes | Amount in smallest unit (wei / token decimals) as a base-10 integer string |
| `callbackUrl` | string | yes | URL the scanner POSTs to on confirmation |
| `callbackSecret` | string | yes | HMAC key for `X-AMN-Signature` verification |
| `confirmations` | integer | no | Override chain default confirmation count (0 = use chain default) |
| `confirmations` | integer | no | Requested confirmation count. The scanner raises it to the chain acceptance floor if lower. |
**Example request:**
@@ -52,9 +52,9 @@ Register a new payment intent. The scanner will watch the specified chain for a
"tokenAddress": "0x55d398326f99059ff775485246999027b3197955",
"destination": "0xAbCd1234...",
"amount": "10000000000000000000",
"callbackUrl": "https://api.amn.gg/api/payment/scanner-callback",
"callbackUrl": "https://api.amn.gg/api/payment/amn-scanner/webhook",
"callbackSecret": "abc123...",
"confirmations": 12
"confirmations": 200
}
```
@@ -79,6 +79,8 @@ Register a new payment intent. The scanner will watch the specified chain for a
}
```
**Confirmation floor**: Built-in accepted thresholds are currently BSC `200`, Ethereum `50`, Polygon `300`, Arbitrum `2400`, Base `300`, Tron `200`, and TON `120`. Callers may raise a requirement but cannot lower an intent below the chain floor.
**Idempotency**: If `intentId` already exists the existing intent's checkout block is returned (no error).
**Error cases:**
@@ -201,6 +203,7 @@ When an intent is confirmed the scanner POSTs to `callbackUrl`:
"paymentReference": "0x1a2b3c4d5e6f7a8b",
"txHash": "0xdeadbeef...",
"blockNumber": 39000010,
"confirmations": 200,
"amount": "10000000000000000000",
"token": "0x55d398326f99059ff775485246999027b3197955",
"chainId": 56,
@@ -208,6 +211,8 @@ When an intent is confirmed the scanner POSTs to `callbackUrl`:
}
```
`confirmations` is the accepted confirmation count. Once the intent is `confirmed`, the scanner caps this value at `confirmationsRequired`; it does not keep reporting a live, ever-growing block count.
**Retry schedule** (on non-2xx or network error): 5 s → 30 s → 2 min → 10 min → 1 h → `webhook_failed`.
The backend should verify `X-AMN-Signature` to reject forged callbacks:
@@ -234,7 +239,7 @@ if (!timingSafeEqual(Buffer.from(received), Buffer.from(expected))) reject();
"paymentReference": "0x1a2b3c4d",
"topicRef": "0xdeadbeef...",
"status": "pending | confirming | confirmed | expired | webhook_failed",
"confirmationsRequired": 12,
"confirmationsRequired": 200,
"txHash": null,
"logIndex": null,
"blockNumber": null,