Confirm a wallet reservation

This is a synchronous API endpoint you must expose, not a webhook. DimeTrades calls it and blocks on the response, in the same request/response cycle as order placement — it is not delivered by the outbox/retry mechanism the wallet.debit/wallet.credit events use, and DimeTrades never waits on anything from you asynchronously here. {partnerApiBaseUrl} is your brand’s own configured base URL, not a fixed DimeTrades host — there’s nothing to “try” against a shared server, since every partner’s URL is different.

Called before accepting a BUY limit order or a cost-increasing modification, for any customer whose brand has external wallet integration enabled (REQ-01). Market orders never call this — they carry no limit price to size the check against, and DimeTrades no longer estimates one on your behalf (see “Reservation sizing” below).

Per your own integration flow, your backend already reserves funds atomically against the customer’s balance before it ever calls DimeTrades’s POST /orders — that atomicity can’t be delegated to a callback. This endpoint is DimeTrades confirming that reservation exists, not instructing you to create one.

Authenticating the request

POST {partnerApiBaseUrl}/v1/wallets/{externalCustomerId}/reserve HTTP/1.1
Authorization: Bearer {partnerApiKeyId}
X-DimeTrades-Signature: t=1786384403,v1=6ac323d7d75b7e9f6cbfce6acc19edc657798f1e30dcd00c933cba5a4000a58b
Content-Type: application/json

externalCustomerId is the id you supplied when the customer was registered through the partner provisioning API — present both in the URL and the body. X-DimeTrades-Signature uses the same t=<unix seconds>,v1=<hex HMAC-SHA256> scheme as webhook deliveries, but signed with your external wallet secret — a separate credential from your webhook signing secret, issued and rotated independently — and computed over this request’s own JSON body, the same way a webhook delivery’s signature covers its body. Full verification steps are in the Verifying a delivery section of the Partner webhooks guide (same scheme, different secret). This signature is the actual proof the call came from DimeTrades — verify it.

Authorization: Bearer {partnerApiKeyId} is also sent, but it is not a credential and not part of authenticating the request: partnerApiKeyId is a plain identifier your brand’s admin typed into DimeTrades’s own settings, not issued, rotated, or cryptographically verified by DimeTrades, and this field is optional on the brand’s side — a brand with it unset still gets this header, just with an empty/placeholder value. Treat it as an optional secondary hint at most, never as something you need to check, and never as a substitute for verifying the signature above.

Reservation sizing

amountCents already includes the worst-case fee: it’s the order’s cost (price × quantity) plus the taker-rate fee, the higher of the two rates DimeTrades ever charges. DimeTrades debits cost + fee on fill (see wallet.debit), and the actual fee applied on fill is always this taker rate or the lower maker rate — never higher. So converting amountCents straight into a settled debit never under-covers the fee; no additional buffer is needed on your side. DimeTrades still has no visibility into your actual reservation and can’t validate or enforce your sizing from its side — this section just documents what amountCents itself already accounts for.

Timeout and retries

DimeTrades retries this check up to 3 times before giving up. The partnerApiTimeoutMs configured for your brand (2000ms by default) applies per attempt, not to the retry sequence as a whole — each of the 3 attempts gets its own full timeout window. Between attempts, DimeTrades waits a short backoff (100ms, then 500ms; no wait after the final attempt).

Worst case, if every attempt times out, this adds up to roughly 6–7 seconds (3 × 2000ms timeout + 100ms + 500ms backoff), not the ~2.6s the backoff schedule alone might suggest — all of it within the lifetime of your customer’s order-placement request. Keep your actual response time well under your configured per-attempt timeout; if all retries fail, the order is rejected — a partner outage blocks that brand’s BUY flow rather than silently letting orders through unchecked.

Rejection mapping

Full context — setup, what happens if POST /orders itself fails or times out, and how release works — is in the External wallet integration guide.