Dfns Webhooks API
Register HTTPS webhooks to receive events for wallet, transfer, signature, and policy activity; ping endpoints and inspect the event delivery log.
OpenAPI Specification
openapi: 3.0.1
info:
title: Dfns API
description: >-
Representative OpenAPI description of the Dfns wallet-as-a-service and MPC
key-management REST API. Covers programmable non-custodial wallets, MPC
keys, transfers and transactions, signature generation, the policy engine
and approvals, webhooks, permissions and authentication (including User
Action Signing), service accounts, and blockchain network reads.
Authentication uses an Authorization Bearer access token (from a service
account token or a user login) plus, for sensitive mutating operations, a
User Action Signature obtained via the User Action Signing challenge/complete
flow and passed in the X-DFNS-USERACTION header.
contact:
name: Dfns Support
url: https://www.dfns.co/
termsOfService: https://www.dfns.co/terms-of-service
version: '1.0'
servers:
- url: https://api.dfns.io
description: Dfns production REST API (Europe / default)
- url: https://api.uae.dfns.io
description: Dfns production REST API (UAE region)
tags:
- name: Wallets
description: Programmable non-custodial wallets, balances, NFTs, and history.
- name: Keys
description: Standalone MPC keys and delegated signing.
- name: Transfers
description: Asset transfers built, signed, and broadcast from a wallet.
- name: Transactions
description: Sign-and-broadcast of caller-supplied transactions from a wallet.
- name: Signatures
description: Raw signature generation from keys.
- name: Policies
description: Policy engine rules and approval decisions.
- name: Approvals
description: Approval workflow driven by the policy engine.
- name: Webhooks
description: Event webhooks and delivery logs.
- name: Permissions
description: Permissions and their assignments to identities.
- name: Auth
description: Login, User Action Signing, users, and credentials.
- name: ServiceAccounts
description: Machine identities and their access tokens.
- name: Networks
description: Network fee estimates and read-only blockchain calls.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Access token issued to a service account or a logged-in user. Sent as
`Authorization: Bearer <token>`.
AppId:
type: apiKey
in: header
name: X-DFNS-APPID
description: The Dfns application (app) id the request is made on behalf of.
UserAction:
type: apiKey
in: header
name: X-DFNS-USERACTION
description: >-
A User Action Signature token proving the caller cryptographically
signed the request payload. Required on sensitive mutating operations
(transfers, signature generation, key/policy/permission changes).
schemas:
Error:
type: object
properties:
error:
type: object
properties:
message:
type: string
code:
type: string
Wallet:
type: object
properties:
id:
type: string
example: wa-6lo9d-9uvpm-9skk4dv0v99cf6bs
network:
type: string
example: EthereumSepolia
address:
type: string
example: '0x8f3a3a...'
signingKey:
type: object
properties:
scheme:
type: string
example: ECDSA
curve:
type: string
example: secp256k1
publicKey:
type: string
status:
type: string
enum: [Active, Archived]
custodial:
type: boolean
name:
type: string
tags:
type: array
items:
type: string
dateCreated:
type: string
format: date-time
WalletList:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Wallet'
nextPageToken:
type: string
nullable: true
WalletAsset:
type: object
properties:
symbol:
type: string
decimals:
type: integer
balance:
type: string
kind:
type: string
example: Native
SignatureRequest:
type: object
properties:
id:
type: string
walletId:
type: string
status:
type: string
enum: [Pending, Executing, Signed, Confirmed, Failed, Rejected]
requestBody:
type: object
signature:
type: object
nullable: true
properties:
r:
type: string
s:
type: string
recid:
type: integer
encoded:
type: string
dateRequested:
type: string
format: date-time
TransferRequest:
type: object
properties:
id:
type: string
walletId:
type: string
network:
type: string
requester:
type: object
status:
type: string
enum: [Pending, Executing, Broadcasted, Confirmed, Failed, Rejected]
txHash:
type: string
nullable: true
Key:
type: object
properties:
id:
type: string
example: key-2s7vg-...
scheme:
type: string
example: ECDSA
curve:
type: string
example: secp256k1
publicKey:
type: string
status:
type: string
enum: [Active, Archived]
custodial:
type: boolean
Policy:
type: object
properties:
id:
type: string
name:
type: string
activityKind:
type: string
example: Wallets:Sign
rule:
type: object
action:
type: object
status:
type: string
enum: [Active, Archived]
Approval:
type: object
properties:
id:
type: string
activityId:
type: string
status:
type: string
enum: [Pending, Approved, Denied, AutoApproved, Expired]
decisions:
type: array
items:
type: object
Webhook:
type: object
properties:
id:
type: string
url:
type: string
status:
type: string
enum: [Enabled, Disabled]
events:
type: array
items:
type: string
description:
type: string
Permission:
type: object
properties:
id:
type: string
name:
type: string
operations:
type: array
items:
type: string
status:
type: string
enum: [Active, Archived]
ServiceAccount:
type: object
properties:
userInfo:
type: object
properties:
userId:
type: string
username:
type: string
isActive:
type: boolean
isServiceAccount:
type: boolean
accessTokens:
type: array
items:
type: object
UserActionChallenge:
type: object
properties:
challenge:
type: string
challengeIdentifier:
type: string
allowCredentials:
type: object
UserActionResponse:
type: object
properties:
userAction:
type: string
description: The User Action Signature token to pass in X-DFNS-USERACTION.
security:
- BearerAuth: []
AppId: []
paths:
/wallets:
post:
operationId: createWallet
tags: [Wallets]
summary: Create a wallet
description: >-
Creates a new non-custodial wallet on a given blockchain network,
backed by an MPC key. Requires a User Action Signature.
security:
- BearerAuth: []
AppId: []
UserAction: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [network]
properties:
network:
type: string
example: EthereumSepolia
name:
type: string
tags:
type: array
items:
type: string
responses:
'200':
description: The created wallet.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
get:
operationId: listWallets
tags: [Wallets]
summary: List wallets
parameters:
- in: query
name: limit
schema:
type: integer
- in: query
name: paginationToken
schema:
type: string
responses:
'200':
description: A paginated list of wallets.
content:
application/json:
schema:
$ref: '#/components/schemas/WalletList'
/wallets/{walletId}:
get:
operationId: getWallet
tags: [Wallets]
summary: Get a wallet by id
parameters:
- in: path
name: walletId
required: true
schema:
type: string
responses:
'200':
description: The wallet.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
/wallets/{walletId}/assets:
get:
operationId: getWalletAssets
tags: [Wallets]
summary: Get wallet assets (balances)
parameters:
- in: path
name: walletId
required: true
schema:
type: string
responses:
'200':
description: The wallet's asset balances.
content:
application/json:
schema:
type: object
properties:
walletId:
type: string
network:
type: string
assets:
type: array
items:
$ref: '#/components/schemas/WalletAsset'
/wallets/{walletId}/nfts:
get:
operationId: getWalletNfts
tags: [Wallets]
summary: Get wallet NFTs
parameters:
- in: path
name: walletId
required: true
schema:
type: string
responses:
'200':
description: The wallet's NFTs.
content:
application/json:
schema:
type: object
/wallets/{walletId}/history:
get:
operationId: getWalletHistory
tags: [Wallets]
summary: Get wallet transfer history
parameters:
- in: path
name: walletId
required: true
schema:
type: string
responses:
'200':
description: The wallet's on-chain history.
content:
application/json:
schema:
type: object
/wallets/{walletId}/transfers:
post:
operationId: transferAsset
tags: [Transfers]
summary: Transfer an asset from a wallet
description: >-
Initiates a native, ERC-20/SPL/token, or NFT transfer from a wallet.
Dfns builds, signs, and broadcasts the transaction. Requires a User
Action Signature and may be gated by the policy engine for approval.
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: walletId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [kind, to]
properties:
kind:
type: string
enum: [Native, Erc20, Erc721, Spl, Sep20]
example: Native
to:
type: string
amount:
type: string
contract:
type: string
responses:
'200':
description: The created transfer request.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequest'
get:
operationId: listTransfers
tags: [Transfers]
summary: List wallet transfer requests
parameters:
- in: path
name: walletId
required: true
schema:
type: string
responses:
'200':
description: A list of transfer requests for the wallet.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/TransferRequest'
nextPageToken:
type: string
nullable: true
/wallets/{walletId}/transfers/{transferId}:
get:
operationId: getTransfer
tags: [Transfers]
summary: Get a wallet transfer request by id
parameters:
- in: path
name: walletId
required: true
schema:
type: string
- in: path
name: transferId
required: true
schema:
type: string
responses:
'200':
description: The transfer request.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequest'
/wallets/{walletId}/transactions:
post:
operationId: broadcastTransaction
tags: [Transactions]
summary: Broadcast a transaction from a wallet
description: >-
Signs and broadcasts a caller-supplied transaction (e.g. a smart
contract call) from the wallet. Requires a User Action Signature.
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: walletId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [kind]
properties:
kind:
type: string
enum: [Transaction, Evm, Eip1559]
transaction:
type: string
description: Hex-encoded unsigned transaction.
responses:
'200':
description: The created transaction broadcast request.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequest'
get:
operationId: listTransactions
tags: [Transactions]
summary: List wallet transaction requests
parameters:
- in: path
name: walletId
required: true
schema:
type: string
responses:
'200':
description: A list of transaction requests for the wallet.
content:
application/json:
schema:
type: object
/keys:
post:
operationId: createKey
tags: [Keys]
summary: Create a key
description: >-
Creates a standalone MPC key (scheme/curve) not bound to a single
network, usable to derive addresses across chains. Requires a User
Action Signature.
security:
- BearerAuth: []
AppId: []
UserAction: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [scheme, curve]
properties:
scheme:
type: string
example: ECDSA
curve:
type: string
example: secp256k1
name:
type: string
responses:
'200':
description: The created key.
content:
application/json:
schema:
$ref: '#/components/schemas/Key'
get:
operationId: listKeys
tags: [Keys]
summary: List keys
responses:
'200':
description: A list of keys.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Key'
nextPageToken:
type: string
nullable: true
/keys/{keyId}:
get:
operationId: getKey
tags: [Keys]
summary: Get a key by id
parameters:
- in: path
name: keyId
required: true
schema:
type: string
responses:
'200':
description: The key.
content:
application/json:
schema:
$ref: '#/components/schemas/Key'
/keys/{keyId}/delegate:
post:
operationId: delegateKey
tags: [Keys]
summary: Delegate a key to an end user
description: >-
Transfers control of a key (and its wallets) to an end user's
credentials, enabling non-custodial delegated signing. Requires a User
Action Signature.
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: keyId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [userId]
properties:
userId:
type: string
responses:
'200':
description: The delegated key.
content:
application/json:
schema:
$ref: '#/components/schemas/Key'
/keys/{keyId}/signatures:
post:
operationId: generateKeySignature
tags: [Signatures]
summary: Generate a signature from a key
description: >-
Produces a raw signature using a standalone MPC key. Requires a User
Action Signature.
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: keyId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [kind]
properties:
kind:
type: string
enum: [Hash, Message]
hash:
type: string
responses:
'200':
description: The signature request.
content:
application/json:
schema:
$ref: '#/components/schemas/SignatureRequest'
/v2/policies:
post:
operationId: createPolicy
tags: [Policies]
summary: Create a policy
description: >-
Creates a policy in the policy engine that governs an activity kind
(e.g. Wallets:Sign) with a rule and an action (Block, RequestApproval,
NoOp). Requires a User Action Signature.
security:
- BearerAuth: []
AppId: []
UserAction: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
responses:
'200':
description: The created policy.
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
get:
operationId: listPolicies
tags: [Policies]
summary: List policies
responses:
'200':
description: A list of policies.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Policy'
/v2/policies/{policyId}:
get:
operationId: getPolicy
tags: [Policies]
summary: Get a policy by id
parameters:
- in: path
name: policyId
required: true
schema:
type: string
responses:
'200':
description: The policy.
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
put:
operationId: updatePolicy
tags: [Policies]
summary: Update a policy
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: policyId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
responses:
'200':
description: The updated policy.
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
delete:
operationId: archivePolicy
tags: [Policies]
summary: Archive (delete) a policy
description: Archives a policy so it no longer governs activities.
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: policyId
required: true
schema:
type: string
responses:
'200':
description: The archived policy.
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
/v2/policy-approvals:
get:
operationId: listApprovals
tags: [Approvals]
summary: List approvals
responses:
'200':
description: A list of approvals awaiting or resolved by decision makers.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Approval'
/v2/policy-approvals/{approvalId}:
get:
operationId: getApproval
tags: [Approvals]
summary: Get an approval by id
parameters:
- in: path
name: approvalId
required: true
schema:
type: string
responses:
'200':
description: The approval.
content:
application/json:
schema:
$ref: '#/components/schemas/Approval'
/v2/policy-approvals/{approvalId}/decisions:
post:
operationId: createApprovalDecision
tags: [Approvals]
summary: Create an approval decision (approve or deny)
description: >-
Records an Approved or Denied decision on a pending approval. Requires
a User Action Signature.
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: approvalId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [value]
properties:
value:
type: string
enum: [Approved, Denied]
reason:
type: string
responses:
'200':
description: The updated approval.
content:
application/json:
schema:
$ref: '#/components/schemas/Approval'
/webhooks:
post:
operationId: createWebhook
tags: [Webhooks]
summary: Create a webhook
security:
- BearerAuth: []
AppId: []
UserAction: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [url, events]
properties:
url:
type: string
events:
type: array
items:
type: string
description:
type: string
responses:
'200':
description: The created webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
get:
operationId: listWebhooks
tags: [Webhooks]
summary: List webhooks
responses:
'200':
description: A list of webhooks.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Webhook'
/webhooks/{webhookId}:
get:
operationId: getWebhook
tags: [Webhooks]
summary: Get a webhook by id
parameters:
- in: path
name: webhookId
required: true
schema:
type: string
responses:
'200':
description: The webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
put:
operationId: updateWebhook
tags: [Webhooks]
summary: Update a webhook
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: webhookId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
responses:
'200':
description: The updated webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
delete:
operationId: deleteWebhook
tags: [Webhooks]
summary: Delete a webhook
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: webhookId
required: true
schema:
type: string
responses:
'200':
description: The webhook was deleted.
/webhooks/{webhookId}/ping:
post:
operationId: pingWebhook
tags: [Webhooks]
summary: Ping a webhook
description: Sends a test event to the webhook to verify connectivity.
parameters:
- in: path
name: webhookId
required: true
schema:
type: string
responses:
'200':
description: The ping result (delivered status and response code).
content:
application/json:
schema:
type: object
/webhooks/{webhookId}/events:
get:
operationId: listWebhookEvents
tags: [Webhooks]
summary: List webhook events
parameters:
- in: path
name: webhookId
required: true
schema:
type: string
responses:
'200':
description: The delivery log of events for the webhook.
content:
application/json:
schema:
type: object
/permissions:
post:
operationId: createPermission
tags: [Permissions]
summary: Create a permission
security:
- BearerAuth: []
AppId: []
UserAction: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Permission'
responses:
'200':
description: The created permission.
content:
application/json:
schema:
$ref: '#/components/schemas/Permission'
get:
operationId: listPermissions
tags: [Permissions]
summary: List permissions
responses:
'200':
description: A list of permissions.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Permission'
/permissions/{permissionId}:
get:
operationId: getPermission
tags: [Permissions]
summary: Get a permission by id
parameters:
- in: path
name: permissionId
required: true
schema:
type: string
responses:
'200':
description: The permission.
content:
application/json:
schema:
$ref: '#/components/schemas/Permission'
/permissions/{permissionId}/assignments:
post:
operationId: createPermissionAssignment
tags: [Permissions]
summary: Assign a permission to an identity
description: Assigns a permission to a user, service account, or PAT.
security:
- BearerAuth: []
AppId: []
UserAction: []
parameters:
- in: path
name: permissionId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [identityId]
properties:
identityId:
type: string
responses:
'200':
description: The created assignment.
content:
application/json:
schema:
type: object
/auth/action/init:
post:
operationId: createUserActionChallenge
tags: [Auth]
summary: Initialize a User Action Signing challenge
description: >-
Starts the User Action Signing flow for a sensitive operation,
returning a challenge the client must sign with its credential.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [userActionPayload, userActionHttpMethod, userActionHttpPath]
properties:
userActionPayload:
type: string
userActionHttpMethod:
type: string
userActionHttpPath:
type: string
responses:
'200':
description: The user action challenge.
content:
application/json:
schema:
$ref: '#/components/schemas/UserActionChallenge'
/auth/action:
post:
operationId: completeUserAction
tags: [Auth]
summary: Complete a User Action Signing challenge
description: >-
Submits the signed challenge and returns a User Action Signature token
to pass in the X-DFNS-USERACTION header of the sensitive request.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [challengeIdentifier, firstFactor]
properties:
challengeIdentifier:
type: string
firstFactor:
type: object
responses:
'200':
description: The user action signature.
content:
application/json:
schema:
$ref: '#/component
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dfns/refs/heads/main/openapi/dfns-openapi.yml