{
"id": "9d2f4b1c-2222-4b22-937f-e78abb9bb42f",
"type": "wallet.credit",
"createdAt": "2026-08-10T17:51:34.103Z",
"data": {
"orderId": "019f2cfa-2fc7-733c-b8af-2fc76797a369",
"clientOrderId": "my-app-order-8f3e2a1b",
"marketId": 60497,
"eventId": 5454,
"tradeId": "a1b2c3d4-0000-1111-2222-333344445555",
"externalCustomerId": "cust-92",
"amountCents": 386,
"reason": "settlement",
"costCents": 400,
"feeCents": 14,
"quantity": 10,
"priceCents": 40,
"role": "taker"
}
}Acknowledge a credit against a partner-managed wallet
Fires when a customer’s position settles for a payout and DimeTrades needs
to tell you how much to add to that customer’s balance. data.reason
tells you why:
reason | When | data |
|---|---|---|
settlement | A SELL order’s proceeds, or an auto-merge payout on a BUY that completed a YES+NO pair | orderId, clientOrderId, marketId, eventId, tradeId, externalCustomerId, amountCents, reason |
trade_bust_reversal | A busted trade is reversed and the cost plus fee of a BUY you debited is refunded | Trade fields as for settlement, mirrored: costCents + feeCents = amountCents |
trade_bust_correction | A bust corrected to fair value: the net of everything owed to this customer for the trade | Trade fields plus breakdown (the parts that were netted) |
price_correction | An admin re-priced a trade and this customer is owed the difference | orderId, tradeId, correctionId, contractSide, oldPriceCents, newPriceCents, quantity, role |
market_settlement | A market resolved YES/NO or was refunded, and the customer holds a paying position | WalletCreditSettlementData below: one event per position, no orderId/tradeId |
Branch on reason, not on which fields are present. Only sent for brands with external wallet integration enabled
(REQ-01); DimeTrades holds no balance of its own for these users, so this
is the authoritative instruction to apply the credit on your side.
Delivered async, signed, at-least-once. Every delivery carries:
X-DimeTrades-Event-Id: 9d2f4b1c-2222-4b22-937f-e78abb9bb42f
X-DimeTrades-Event-Type: wallet.credit
X-DimeTrades-Signature: t=1786384403,v1=6ac323d7d75b7e9f6cbfce6acc19edc657798f1e30dcd00c933cba5a4000a58b
v1 is HMAC-SHA256(webhookSecret, "{t}.{rawBody}"), hex-encoded. Verify it, and reject stale timestamps, before trusting the payload. Retried with exponential backoff (30s -> 2m -> 10m -> 1h -> 6h) up to 8 attempts if your endpoint doesn’t return 2xx; dedupe on id since a retried delivery reuses the same event id — applying the same credit twice would overpay your customer. Full details in the Partner webhooks guide.
{
"id": "9d2f4b1c-2222-4b22-937f-e78abb9bb42f",
"type": "wallet.credit",
"createdAt": "2026-08-10T17:51:34.103Z",
"data": {
"orderId": "019f2cfa-2fc7-733c-b8af-2fc76797a369",
"clientOrderId": "my-app-order-8f3e2a1b",
"marketId": 60497,
"eventId": 5454,
"tradeId": "a1b2c3d4-0000-1111-2222-333344445555",
"externalCustomerId": "cust-92",
"amountCents": 386,
"reason": "settlement",
"costCents": 400,
"feeCents": 14,
"quantity": 10,
"priceCents": 40,
"role": "taker"
}
}Authorizations
HMAC request/delivery signature — not a bearer token or API key. The actual proof a call came from DimeTrades — verify it.
Used on webhook deliveries and on the external-wallet reservation check:
t=<unix seconds>,v1=<hex HMAC-SHA256>, where v1 is
HMAC-SHA256(secret, "{t}.{rawBody}") over the exact raw body sent.
Webhook deliveries are signed with your webhook signing secret; the
reservation check is signed with your separate external wallet secret.
Verify the signature and reject stale timestamps before trusting the
payload — full steps in the Partner webhooks guide's "Verifying a
delivery" section. Neither of these calls carries X-API-Key — that
identifies a platform calling DimeTrades; here DimeTrades is calling
you, with its own identity proven by this signature, not by any
header, alone.
The reservation check also carries Authorization: Bearer {partnerApiKeyId}, but that header is not part of authentication —
partnerApiKeyId is a plain identifier your brand's admin typed into
DimeTrades's settings, not issued or cryptographically verified by
DimeTrades, and it's optional on the brand's side. Treat this signature
as the only thing that actually proves the call is legitimate; see the
reservation check's own "Authenticating the request" section for that
header's details.
Body
The payload DimeTrades sends to your webhookUrl.
Every webhook delivery shares this envelope. id is stable across retries — use it to dedupe. data varies per type; see each webhook page.
Stable per-event id. Identical across delivery retries — dedupe on this.
One of the webhook event names, e.g. order.filled, trade.executed.
Event-specific payload — see the individual webhook for its shape. Every order.*, trade.executed and wallet.* event carries orderId, clientOrderId (the key you supplied on POST /orders; null only for an order placed without one), marketId, eventId (the event the market belongs to) and externalCustomerId (your own id for the customer, as supplied when you registered them), so you can correlate on your own keys without a lookup. The exception is a wallet.credit with reason: market_settlement, which has no order behind it and carries marketId and positionId instead.
- WalletCreditTradeData
- WalletCreditSettlementData
Show child attributes
Show child attributes
Response
Return any 2xx to acknowledge receipt. Anything else (including a timeout) is treated as a delivery failure and retried.