Create a wallet for one of your customers
Proposes one wallet under organisation policy; never approves it. Opt-in per organisation: until MegTrust enables wallet creation for yours, every call returns 403 wallet_create_not_enabled and nothing is created. Safe to retry: one Idempotency-Key and one external_ref per wallet, each unique within the organisation. Same key and body return the current state — 202 while pending (no wallet yet), 201 or 200 with the wallet once active, 422 wallet_create_failed if the create did not go through. Retrying a 422 with the same key is always safe: a failed or expired create is tried again for the same wallet, up to three proposals; a decline under policy, or a create that failed three times, is final and keeps answering 422 from the stored request with no new attempt. A different body under the key, or the external_ref under another key, returns 409. Every request carries `customer`; MegTrust screens that customer first, so a new request answers 202 while screening runs. A customer who does not pass is refused for good: 422 wallet_create_refused, and no wallet is proposed.
/api/v1/walletsProposes one wallet under organisation policy; never approves it. Opt-in per organisation: until MegTrust enables wallet creation for yours, every call returns 403 wallet_create_not_enabled and nothing is created. Safe to retry: one Idempotency-Key and one external_ref per wallet, each unique within the organisation. Same key and body return the current state — 202 while pending (no wallet yet), 201 or 200 with the wallet once active, 422 wallet_create_failed if the create did not go through. Retrying a 422 with the same key is always safe: a failed or expired create is tried again for the same wallet, up to three proposals; a decline under policy, or a create that failed three times, is final and keeps answering 422 from the stored request with no new attempt. A different body under the key, or the external_ref under another key, returns 409. Every request carries customer; MegTrust screens that customer first, so a new request answers 202 while screening runs. A customer who does not pass is refused for good: 422 wallet_create_refused, and no wallet is proposed.
Authorization
KeyId Timestamp Signature Key ID registered by your organisation administrator.
In: header
Unix seconds within ±300 seconds of the server clock.
In: header
Padded base64 Ed25519 signature over timestamp, METHOD, exact path+query, lowercase SHA256(raw body), Idempotency-Key or empty string, joined with LF. Legacy HMAC uses lowercase hex HMAC-SHA256. Signing is required; entering a static value is insufficient.
In: header
Query Parameters
Fresh random UUID per attempt, included in the signed path. Avoids duplicate signatures for identical requests in the same second.
uuidHeader Parameters
^[\x21-\x7e]{1,128}$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/wallets" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "network": "string", "external_ref": "string", "customer": { "type": "company", "legal_name": "string", "country": "st", "risk_rating": "low", "approved_by": "string", "approved_at": "2019-08-24T14:15:22Z" } }'{ "data": { "id": "string", "status": "pending", "external_ref": "string", "wallet_id": "string", "wallet": { "id": "string", "name": "string", "status": "active", "address": "string", "deposit_addresses": [ { "network": "string", "network_name": "string", "address": "string" } ], "networks": [ { "id": "string", "name": "string" } ], "balances": [ { "asset": "string", "network": "string", "amount": "string", "available": "string", "usd_value": 0 } ], "total_usd": 0 } }, "meta": { "count": 0, "limit": 0, "offset": 0, "next_offset": 0, "idempotent_replay": true, "already_exists": true, "stale": true }}Delivery to your registered HTTPS receiver Webhook
Verify raw bytes with the endpoint secret: HMAC-SHA256(timestamp + '.' + raw body), ±5 minutes. Durably deduplicate event.id. Deliveries may be delayed, duplicated and out of order; up to eight attempts. Respond within 10 seconds after durably accepting the event.
Changelog
Changes to the MegTrust Client API. Breaking changes ship as a new version path; v1 only grows.