Smart wallet API overview

DALP smart wallet endpoints let integrations operate ERC-4337 smart wallets through the API. Use them to discover wallets where the authenticated user is a signer, check gas readiness, manage supported signer and validator-module configuration, and coordinate multisig approvals without bypassing account-abstraction controls.

This page is a reference for integration developers. For the concept model behind smart accounts, EntryPoint routing, bundlers, paymasters, and validators, see Account abstraction model, UserOperations, and Paymasters and gas sponsorship. For the general API entry point, see API reference. For the dedicated approval and threshold workflows, see Smart wallet approvals and Smart wallet thresholds.

When to use smart wallet endpoints

Use /api/v2/smart-wallets when your integration needs to:

• list smart wallets where the authenticated user is a signer
• read a wallet's owner, validators, signers, threshold, and metadata
• check gas status before submitting account-abstraction operations
• deploy a smart wallet with the default validator or weighted multisig configuration
• update the wallet description stored off-chain
• install or remove ERC-7579 validator modules
• add default-weight multisig signers, remove signers, and list signer weights
• create, inspect, and sign multisig approvals for pending user operations

Smart wallet mutations that change on-chain configuration use the transaction queue. The API can return the completed wallet envelope with transaction hashes, or an accepted transaction with transactionId, status, and statusUrl. Persist that status information and poll the status URL when the async shape is present.

Provisioning and first use

When account abstraction is enabled for a participant, DALP can return a smart wallet address before the account has bytecode on-chain. Treat the API-returned address as the participant's canonical smart wallet address. Do not use bytecode existence alone to decide whether the wallet exists in DALP.

Provisioning is idempotent for a participant. If DALP already has a smart wallet row for that participant, the API reuses that wallet address instead of deriving a new one. For newly provisioned wallets, the workflow treats the smart-wallet step as complete only after it has both the wallet address and the deployment block used for indexed follow-on reads. This keeps dependent API reads from racing a wallet that has been submitted on-chain but is not indexed yet.

If the indexer does not catch up in time, callers may see Smart wallet {address} not found after indexing. The indexer may not have processed the AccountCreated event yet. Retry the request or continue polling the returned status URL instead of deriving a different wallet address.

For integrations, this means:

• store the smart wallet address DALP returns for the participant
• reuse the returned address for later executor selection and gas-status checks
• handle mutating requests as asynchronous operations when DALP returns status information
• poll the returned status URL instead of treating a newly returned address as already deployed
• wait until a newly provisioned wallet can be read from the API before starting dependent work

Executor selection with X-Executor

Most API callers can omit X-Executor and let DALP choose the active executor for the authenticated participant and organization policy.

Send X-Executor only when the request must force a specific execution wallet. See Request headers for the complete X-Participant and X-Executor contract.

DALP validates the selected participant and executor before queueing a blockchain operation. Invalid participant IDs, unsupported executor values, missing signer wallets, or unresolved smart-wallet execution fail before submission.

Response shape

List and read endpoints return smart wallet records with address, factory, owner, defaultValidator, identity, system, threshold, validators, signers, description, and createdAt. Configured weighted-multisig thresholds and signer weight values are decimal strings because the underlying validator uses integer weights on-chain. Default ECDSA wallets or legacy rows can return threshold: null; ECDSA signers have weight: null.

On-chain mutations can finish in the request or continue asynchronously:

Treat the async status as the source of truth while the operation is queued. Do not derive a new wallet address or resubmit signer changes just because the read endpoint has not indexed the result yet.

Endpoint groups

Wallet discovery and metadata

The list endpoint supports pagination, filtering, sorting, global search, and faceted counts. It can filter by walletAddress, ownerAddress, factoryAddress, createdAt, and description; the default sort is newest first by createdAt.

For gas-status checks, pass systemAddress when the wallet has not yet been assigned an indexed system. DALP uses the wallet's indexed system when present, falls back to the supplied systemAddress only when the wallet has no system assignment, and rejects a supplied systemAddress that conflicts with the wallet's indexed system.

The gas status endpoint returns three fields: walletBalance as a wei string, hasPaymaster as the paymaster-sponsorship check for the wallet's system, and chainZeroGas for chains where native gas is not required. When the wallet already has an indexed system, any supplied systemAddress must match it; otherwise DALP uses the wallet's own system for the paymaster check.

Signers and threshold

The threshold is a weighted approval value, not a signer count. The add-signer endpoint currently adds a multisig signer with the default weight 1; it does not accept non-default signer weights. Before changing the threshold, read the signer list and choose a value that can be met by the configured signer weights.

When creating a multisig wallet, each signer address must be unique, must not be the zero address, and carries a positive decimal-string weight that fits in uint64. The total signer weight must meet or exceed the requested threshold, and the authenticated signing wallet must appear in the initial signer list so the creator can operate the wallet after deployment.

Validator modules

Install only validator modules that are supported by your platform configuration and operational policy. Treat module installation and removal as on-chain configuration changes.

Multisig approvals

Use approvals when a smart wallet operation requires signer weight beyond the initiating signer. Co-signers approve through the approval endpoints instead of calling owner-only configuration endpoints directly.

Basic integration sequence

1. List smart wallets with GET /api/v2/smart-wallets and select the wallet address your integration should operate.
2. Read the wallet with GET /api/v2/smart-wallets/{address} to inspect validators, signers, threshold, and metadata.
3. Check GET /api/v2/smart-wallets/{address}/gas-status before submitting account-abstraction operations.
4. For multisig wallets, list signers and approvals before changing signer configuration or threshold values.
5. Submit mutations with idempotency and async status handling, then poll the returned status URL when present. For newly provisioned wallets, wait until the wallet can be read from the API before starting dependent work.

curl "https://your-platform.example.com/api/v2/smart-wallets?sort=-createdAt" \
  -H "X-Api-Key: YOUR_DALP_API_KEY"

{
  "data": [
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "factory": "0xa000000000000000000000000000000000000001",
      "owner": "0xb000000000000000000000000000000000000002",
      "defaultValidator": "0xc000000000000000000000000000000000000003",
      "identity": "0xd000000000000000000000000000000000000004",
      "system": "0xe000000000000000000000000000000000000005",
      "threshold": "1",
      "validators": [
        {
          "moduleAddress": "0xc000000000000000000000000000000000000003",
          "moduleTypeId": "0x3416df84d2590b362d85f374b9811d696e50d684e6d62cc82cb7edbaa13289e0",
          "isInstalled": true
        }
      ],
      "signers": [
        {
          "signer": "0xb000000000000000000000000000000000000002",
          "validatorAddress": "0xc000000000000000000000000000000000000003",
          "weight": "1"
        }
      ],
      "description": "Treasury operations wallet",
      "createdAt": "2026-05-24T08:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "ownerAddress": [
        {
          "value": "0xb000000000000000000000000000000000000002",
          "count": 1
        }
      ],
      "factoryAddress": [
        {
          "value": "0xa000000000000000000000000000000000000001",
          "count": 1
        }
      ]
    }
  },
  "links": {
    "self": "/v2/smart-wallets?sort=-createdAt&page%5Boffset%5D=0&page%5Blimit%5D=50",
    "first": "/v2/smart-wallets?sort=-createdAt&page%5Boffset%5D=0&page%5Blimit%5D=50",
    "prev": null,
    "next": null,
    "last": "/v2/smart-wallets?sort=-createdAt&page%5Boffset%5D=0&page%5Blimit%5D=50"
  }
}

curl "https://your-platform.example.com/api/v2/smart-wallets/0x1234567890abcdef1234567890abcdef12345678/gas-status" \
  -H "X-Api-Key: YOUR_DALP_API_KEY"

{
  "data": {
    "hasPaymaster": true,
    "walletBalance": "0",
    "chainZeroGas": false
  },
  "links": {
    "self": "/v2/smart-wallets/0x1234567890abcdef1234567890abcdef12345678/gas-status"
  }
}

If a mutating request returns status: "QUEUED", poll the returned statusUrl and wait for completion before starting work that depends on the new wallet, signer set, threshold, or module state.

Related

• API reference
• Request headers
• Account abstraction model
• Smart wallet approvals
• Smart wallet thresholds
• System paymasters
• Bundler endpoint