> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign typed data with a wallet

> Returns the wallet's typed-data signature: its EIP-712 signature over structured data that a contract later verifies, such as an order. Nothing is sent on chain.

The wallet must be an EVM wallet. A policy on the wallet needs a `typed_data_allowlist` rule whose entry names the document's chain, `domain.verifyingContract` and `primaryType`, and the request needs as many approver signatures as that rule's `threshold`. Typed-data signatures are not available on an x402 payer wallet, on a wallet with a mandate or an agent signer, or for a document whose `domain.verifyingContract` is the contract of an asset Dakota supports on that chain. The verifying contract is screened like a transaction destination.

`X-Idempotency-Key` is required, as on other POST endpoints, but a response is never replayed for it, because the response is a signature that can authorize a spend. A repeat is decided by the signed `intent.idempotency_key`: the same key and the same intent return the same signature, even when the customer can no longer move money. Once a signature is stored, the same key with a different intent returns `409`. Before a signature is stored, a different request under the same key returns `400`: another document, or the same intent with other approver signatures. A key is tied to your client for 24 hours, not to one wallet. Two identical requests sent at the same moment may get `502` or `503` for one of them; a repeat then returns the stored signature.



## OpenAPI

````yaml /openapi.yaml post /wallets/{wallet_id}/sign
openapi: 3.0.3
info:
  title: Dakota Platform API
  version: 1.0.0
  description: >-
    Combined API specification for Dakota Platform services:

    - Issuance API: Asset minting and burning operations

    - Onboarding API: Know Your Business/Customer verification

    - On/Off Ramp API: Managing on-ramp and off-ramp accounts

    - Recipients API: Managing destinations for KYB'd entities

    - Transactions API: Viewing transaction history across platform operations


    ## Authentication and API Headers


    All API endpoints require the following headers:


    - `X-Idempotency-Key`: Required for all POST endpoints to ensure request
    idempotency

    - `x-api-key`: Required for authentication across all endpoints


    Note: On /applications endpoints you need a token for authentication instead
    of a x-api-key

    - `x-application-token`: Required for authentication on public /applications
    endpoints (alternative to `x-api-key` where documented)



    ## Rate Limits


    Requests are rate limited per API key. Every response includes the following
    headers:


    | Header | Description |

    | --- | --- |

    | `X-RateLimit-Limit` | Maximum requests allowed in the current one-minute
    window. |

    | `X-RateLimit-Remaining` | Requests remaining in the current window. |

    | `X-RateLimit-Reset` | Absolute Unix timestamp (seconds since epoch) when
    the current rate-limit window resets. |


    When a request is throttled (`429`), responses also include `Retry-After`
    with seconds to wait before retrying.
servers:
  - url: https://api.platform.dakota.xyz
    description: Production environment
  - url: https://api.platform.sandbox.dakota.xyz
    description: Sandbox — safe for testing with simulated data
security:
  - ApiKeyAuth: []
tags:
  - name: Agentic Payments
    x-beta: true
    description: >-
      Beta — agent-driven payments: provision agents, draft and approve spending
      mandates, accept reviewed instructions, and manage scheduled payments.


      **Prerequisites:** Customer onboarded; signer groups attached for
      recognition.

      **Related:** Wallets, Signer Groups, Transactions
  - name: Mandates
    x-beta: true
    description: >-
      Beta — spending mandates: signed, signer-bound authorizations governing
      what may be spent, approved or cancelled by a second recognized signer (§8
      — the dual-control rule that every mandate mutation must be signed by a
      recognized signer OTHER than the bound one). Independent of agents and
      scheduled payments.


      **Prerequisites:** Signer groups attached for recognition.

      **Related:** Signer Groups, Transactions
  - name: Insights
    x-beta: true
    description: >-
      Beta — read-only insight: a deterministic report over a customer's agentic
      activity (funding balances, upcoming obligations, failures, mandate
      headroom and expiry), or — via `GET /insights` — over the whole client's
      book, with portfolio KPIs, daily series and a per-customer roll-up. Never
      moves money, never creates or changes anything.


      **Prerequisites:** Customer onboarded; insight is computed from the
      customer's scheduled payments, mandates, and wallets.

      **Related:** Agentic Payments, Mandates
  - name: Customers
    description: >-
      Manage customer entities representing businesses and organizations
      onboarded to Dakota.


      **Prerequisites:** Complete KYB via Onboarding endpoints before initiating
      money movement.

      **Related:** Onboarding, Recipients, Transactions, Accounts, Wallets
  - name: Wallets
    description: >-
      Manage wallets, balances, and wallet-to-signer-group relationships for
      custody and movement controls.


      **Prerequisites:** Customer must exist. Configure signer groups before
      policy-enforced workflows.

      **Related:** Signer Groups, Policies, Transactions, Customers
  - name: Transactions
    description: >-
      Create, cancel, and retrieve transaction records across account and wallet
      flows.


      **Prerequisites:** Accounts or destinations must be configured based on
      flow type.

      **Related:** Accounts, Recipients, Policies, Events
  - name: Recipients
    description: >-
      Manage recipient entities and destination rails used by customers for
      payouts and transfers.


      **Prerequisites:** Customer must be onboarded and active.

      **Related:** Customers, Transactions, Accounts, Onboarding
  - name: Cards
    description: >-
      Issue and manage cardholders and cards, and follow card transactions.
      Every change is also delivered as a webhook event.


      **Prerequisites:** Customer must be onboarded and the cards capability
      must be available.

      **Related:** Customers, Wallets, Events


      ### Webhook event catalog (v1)


      Every card-family event a client can subscribe to, in one place:


      | Event | Fires when |

      | -- | -- |

      | `cardholder.created` | A cardholder is created. |

      | `cardholder.updated` | Any cardholder change, including every
      review-status transition and deletion (`status: closed`). |

      | `cardholder.information_requested` | A reviewer asks for more
      information; the payload lists the open requirements. |

      | `card.created` | A card is created. |

      | `card.updated` | Any card change: status, spend limit, last4, freeze
      sources. A close arrives here with `status: closed`. |

      | `card_transaction.created` | The first event for a transaction, normally
      an authorization (`status: authorized`) placing a hold. A declined
      authorization also arrives here, with `status: declined`. |

      | `card_transaction.updated` | Every later change to the same transaction
      (see below). |

      | `wallet.card_enablement.completed` | A wallet's card-settlement
      enablement became active. |


      **Card event ordering.** `card.created` and `card.updated` carry the card
      as it stands after

      the change, including `version` and `freeze_sources` (always an array,
      empty when nothing

      holds the card). `version` is strictly increasing per card and matches the
      `version` on the

      card resource. Deliveries can arrive out of order, so keep the highest
      `version` you have

      applied for each card and drop any event whose `version` is not greater
      than it.


      **One transaction stream.** Holds, releases, partial clearings,
      settlement, returns,

      disputes and force posts are not separate event types. They are `status`
      transitions on

      the transaction, delivered as `card_transaction.updated` with the same
      payload shape as

      `card_transaction.created`:


      | What happened | `status` on the event |

      | -- | -- |

      | Transaction known before its first authorization event | `pending` (on
      `card_transaction.created`) |

      | Hold placed (authorization) | `authorized` (on
      `card_transaction.created`, or `card_transaction.updated` after a
      `pending` start) |

      | Hold released without clearing (merchant, issuer or network reversal) |
      `auth_reversed` |

      | Hold expired unused | `expired` |

      | Part of the hold settled | `partially_cleared` (with the new
      `cleared_amount`) |

      | Fully settled | `cleared` |

      | Settled with no prior hold | `force_posted` |

      | Merchant refund | `returned`, usually on a new card transaction for the
      refund while the original purchase stays `cleared`. A refund can also land
      on the purchase's own transaction, which keeps its purchase status until
      the refunds cover everything that cleared and nothing authorized is left
      to clear. A transaction carries a refund whenever `refund_state` has a
      value, whatever its `status`. `returned_amount` is how much was refunded.
      The network returned the money; read `refund_state` for whether it reached
      the customer's wallet: `pending` while owed, then `paid`; `reversed` when
      every refund was cancelled before payout; `failed` when a payout failed.
      `returned` alone is not proof of payout. |

      | Merchant refund on its own transaction, fully reversed before it is paid
      out | `auth_reversed` on the refund's card transaction, with
      `refund_state: reversed`. The refund is withdrawn; `refund_state` is what
      tells it from a released hold. |

      | Chargeback opened | `disputed` (reserved; not emitted yet) |

      | Authorization refused | `declined` (on `card_transaction.created`, or
      `card_transaction.updated` when the transaction already exists). Moves no
      money; read `decline_reason` and `decline_code` for why. |


      `outstanding_amount` is the part of `cleared_amount` that no authorization
      covered, less any refunds: non-zero after a force post or an over-capture.


      **Naming.** A dotted segment names a sub-resource of the resource before
      it, so

      `wallet.card_enablement.*` is a wallet's card enablement.
      `card_transaction.*` carries an

      underscore because the resource is `card_transactions`, a top-level
      resource, not a

      sub-resource of a card. It is not a typo, and there is no
      `card.transaction.*` family, and

      no separate settlement event: settlement is a `status` on
      `card_transaction.updated`.


      **Two states on a dispute report, and neither derives from the other.**
      `filing_state`

      is how far the automated filing with the provider has got. `state` is the
      Dakota operator

      workflow, where `filed_at_vendor` still means a person filed by hand. A
      successful

      automated filing does not move `state`. Read the one you mean.
  - name: Accounts
    description: >-
      Manage account resources used for onramp, offramp, and swap operations.


      **Prerequisites:** Customer must be created and network/asset constraints
      must be known.

      **Related:** Customers, Transactions, Auto Transactions, Info
  - name: Auto Transactions
    description: >-
      Manage automated transaction configurations and execution history for
      account automation workflows.


      **Prerequisites:** Source account must exist and be configured for
      automation.

      **Related:** Accounts, Transactions, Events
  - name: Onboarding
    description: >-
      Manage KYB/KYC onboarding lifecycle, application documents, attestations,
      and verification steps.


      **Prerequisites:** Customer context and required entity/application
      metadata.

      **Related:** Customers, Exceptions, Recipients, Transactions
  - name: Policies
    description: >-
      Define and manage policy objects and rules used for transaction governance
      and risk controls.


      **Prerequisites:** Wallet and signer group resources should be configured
      for enforcement scenarios.

      **Related:** Wallets, Signer Groups, Transactions
  - name: Signer Groups
    description: >-
      Manage signer groups and signer assignments for multi-party authorization
      models.


      **Prerequisites:** Wallets should exist before linking signer groups.

      **Related:** Wallets, Policies, Transactions
  - name: Authentication
    description: >-
      Manage API authentication credentials and key lifecycle for platform
      access.


      **Prerequisites:** Client organization must be provisioned.

      **Related:** Users, Info
  - name: Users
    description: >-
      Manage client users, roles, and identity metadata for platform access
      control.


      **Prerequisites:** Auth credentials and client context must be
      established.

      **Related:** Authentication
  - name: Webhooks
    description: >-
      Manage outbound webhook targets and delivery configuration for event
      notifications.


      **Prerequisites:** Subscriber endpoint must be reachable and secured.

      **Related:** Events, Authentication
  - name: Payouts
    description: >-
      Manage where Dakota sends your accrued developer-fee payouts.


      **Prerequisites:** Auth credentials and client context must be
      established.

      **Related:** Events
  - name: RD Marketing Fee
    description: >-
      Everything behind your RD marketing fee: read what a month came to,
      declare the wallets you hold outside Dakota so the RD in them counts, and
      say where the fee should be sent.


      **Prerequisites:** Client must be in the RD marketing-fee programme. A
      month is readable once it has closed.

      **Related:** Wallets, Events
  - name: Self Serve
    description: >-
      Buy and track prepaid credits, and read the tiers and pricing they are
      sold at.


      **Prerequisites:** Auth credentials and client context must be
      established.

      **Related:** Billing
  - name: Events
    description: >-
      Retrieve event records emitted by platform operations for audit and
      troubleshooting.


      **Prerequisites:** Requesting client must have access to referenced
      resources.

      **Related:** Webhooks, Transactions, Onboarding
  - name: Info
    description: >-
      Read platform capability metadata, such as supported rails, networks, and
      assets.

      These operations are served under `/capabilities/*` - `GET
      /capabilities/countries`

      and `GET /capabilities/networks`. The tag name does not appear in the
      request paths.


      **Prerequisites:** Valid authentication headers.

      **Related:** Accounts, Transactions
  - name: Sandbox
    description: >-
      Trigger sandbox-only simulation endpoints for safe end-to-end integration
      testing with synthetic data. The sandbox host
      (`https://api.platform.sandbox.dakota.xyz`) also accepts a family of
      `X-Sandbox-*` request headers on most write endpoints (`Customers`,
      `Accounts`, `Transactions`, simulate endpoints) that let integrators drive
      deterministic failure modes — pick a preset via `X-Sandbox-Scenario`, or
      compose a custom one with
      `X-Sandbox-Error-Step`/`X-Sandbox-Error-Status`/`X-Sandbox-Error-Message`.
      `X-Sandbox-Instant-Completion` collapses async flows to a single
      synchronous step, and `X-Sandbox-Skip-Auto-Approval` keeps newly created
      KYB applications in `pending` for manual-review testing. All `X-Sandbox-*`
      headers are ignored in production.


      **Prerequisites:** Sandbox environment and test customer data.

      **Related:** Customers, Accounts, Transactions, Onboarding
  - name: Legal
    description: |-
      The legal documents customers accept — terms of service, privacy policy,
      e-sign notice, and partner agreements.

      Dakota publishes these here, and this is the authoritative source: the
      hosted onboarding flow, the dakota.xyz website, and your own integration
      all read the same revisions. Present the current revision to your customer
      before capturing their acceptance so the record reflects the text they
      actually saw.
paths:
  /wallets/{wallet_id}/sign:
    post:
      tags:
        - Wallets
      summary: Sign typed data with a wallet
      description: >-
        Returns the wallet's typed-data signature: its EIP-712 signature over
        structured data that a contract later verifies, such as an order.
        Nothing is sent on chain.


        The wallet must be an EVM wallet. A policy on the wallet needs a
        `typed_data_allowlist` rule whose entry names the document's chain,
        `domain.verifyingContract` and `primaryType`, and the request needs as
        many approver signatures as that rule's `threshold`. Typed-data
        signatures are not available on an x402 payer wallet, on a wallet with a
        mandate or an agent signer, or for a document whose
        `domain.verifyingContract` is the contract of an asset Dakota supports
        on that chain. The verifying contract is screened like a transaction
        destination.


        `X-Idempotency-Key` is required, as on other POST endpoints, but a
        response is never replayed for it, because the response is a signature
        that can authorize a spend. A repeat is decided by the signed
        `intent.idempotency_key`: the same key and the same intent return the
        same signature, even when the customer can no longer move money. Once a
        signature is stored, the same key with a different intent returns `409`.
        Before a signature is stored, a different request under the same key
        returns `400`: another document, or the same intent with other approver
        signatures. A key is tied to your client for 24 hours, not to one
        wallet. Two identical requests sent at the same moment may get `502` or
        `503` for one of them; a repeat then returns the stored signature.
      operationId: signWalletTypedData
      parameters:
        - name: wallet_id
          in: path
          required: true
          description: Wallet ID
          schema:
            $ref: '#/components/schemas/KSUID'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignTypedDataRequest'
            example:
              signatures:
                - LS0tLS1CRUdJ...0tLS0tCg==
              intent:
                wallet_id: 1NFHrqBHb3cTfLVkFSGmHZqdDPi
                caip2: eip155:8453
                typed_data: >-
                  {"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"version","type":"string"},{"name":"chainId","type":"uint256"},{"name":"verifyingContract","type":"address"}],"Order":[{"name":"maker","type":"address"},{"name":"amount","type":"uint256"}]},"primaryType":"Order","domain":{"name":"Example
                  Exchange","version":"1","chainId":8453,"verifyingContract":"0xabcdef0123456789abcdef0123456789abcdef01"},"message":{"maker":"0x1234567890abcdef1234567890abcdef12345678","amount":"1000000"}}
                idempotency_key: 4f1c2b8e-7a3d-4e5f-9b6a-1c2d3e4f5a6b
      responses:
        '200':
          description: >-
            The wallet's signature over the document. A repeat with the same
            `idempotency_key` and the same intent returns the stored signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTypedDataSignature'
              example:
                id: 2NFHrqBHb3cTfLVkFSGmHZqdDPj
                wallet_id: 1NFHrqBHb3cTfLVkFSGmHZqdDPi
                caip2: eip155:8453
                signature: >-
                  0x8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f1b
                created_at: 1781181600
        '400':
          description: >-
            Bad request - the request or the document is not valid, the wallet
            is not an EVM wallet, the customer is not KYB-approved, the
            verifying contract did not pass compliance screening, a different
            request was already sent under the same `idempotency_key`, or the
            wallet could not sign the document. The wallet cannot sign a
            document whose `message` does not fit the types it declares; nothing
            is stored, and a corrected document needs a new `idempotency_key`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#invalid-request
                title: Bad request
                status: 400
                detail: >-
                  invalid intent: typed_data: domain.chainId must equal the
                  chain of caip2 "eip155:8453"
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: >-
                  https://docs.dakota.xyz/api-reference/errors#authentication-error
                title: Unauthorized
                status: 401
                detail: Unauthorized
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '403':
          description: >-
            Forbidden - the wallet's policies do not allow this signature, the
            wallet cannot give typed-data signatures, the document is for a
            supported asset's contract, or the customer cannot move money
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#forbidden
                title: Forbidden
                status: 403
                detail: >-
                  typed-data signatures are not available on an x402 payer
                  wallet
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#not-found
                title: Not Found
                status: 404
                detail: Not Found
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '409':
          description: >-
            Conflict - the `idempotency_key` was already used on this wallet for
            a different intent
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#conflict
                title: Typed-data signature Conflict
                status: 409
                detail: >-
                  This idempotency key was already used for a different
                  typed-data sign intent on this wallet.
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#internal-error
                title: Internal server error
                status: 500
                detail: Internal server error
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '502':
          description: >-
            The wallet did not produce a signature. Nothing was stored. The
            `detail` says which of two cases applies. When the wallet provider
            did not answer, send the same request again, with the same approver
            signatures. A request with newly collected approver signatures under
            the same `idempotency_key` is refused. When the wallet provider
            answered without a signature, it gives the same answer to that
            `idempotency_key` for 24 hours, so send the intent again with a new
            `idempotency_key` and new approver signatures.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#provider-error
                title: Provider Error
                status: 502
                detail: >-
                  The wallet provider answered without a signature. Nothing was
                  stored. It gives the same answer to this idempotency_key for
                  24 hours, so send the intent again with a new idempotency_key
                  and new approver signatures.
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
        '503':
          description: |
            Service unavailable. A `reason` of `check_unavailable` (type
            `#check-unavailable`) means the verifying contract's address screen
            could not run, so nothing was signed; retry with backoff under the
            same `idempotency_key`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: >-
                  https://docs.dakota.xyz/api-reference/errors#service-unavailable
                title: Service unavailable
                status: 503
                detail: Service unavailable
                instance: https://api.platform.dakota.xyz/wallets/example-id/sign
                request_id: req_01hzy6y7v8w9x0y1z2a3b4c5d6
components:
  schemas:
    KSUID:
      type: string
      title: KSUID
      description: >-
        KSUID is a 27-character globally unique ID that combines a timestamp
        with a random component. Used for all entity identifiers in the Dakota
        platform.
      pattern: ^[0-9A-Za-z]{27}$
      minLength: 27
      maxLength: 27
      example: 1NFHrqBHb3cTfLVkFSGmHZqdDPi
    SignTypedDataRequest:
      type: object
      description: >-
        A request for a wallet's EIP-712 signature over a typed-data document,
        endorsed by the approvers' signatures over the intent.
      required:
        - signatures
        - intent
      properties:
        signatures:
          type: array
          description: List of signatures over the intent
          items:
            type: string
            description: |
              Cryptographic signature over the intent, base64-encoded. For an
              ES256 signer this is the ASN.1 DER ECDSA signature over the
              SHA-256 of the canonical intent. For a WEBAUTHN signer this is
              the base64 of the WebAuthn assertion JSON (id, rawId, type, and
              response.authenticatorData / clientDataJSON / signature). See
              the WebAuthn & Passkey Signing guide.
            example: LS0tLS1CRUdJ...0tLS0tCg==
        intent:
          $ref: '#/components/schemas/SignTypedDataIntent'
    WalletTypedDataSignature:
      type: object
      description: An EIP-712 signature a wallet gave over a typed-data document.
      required:
        - id
        - wallet_id
        - caip2
        - signature
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/KSUID'
        wallet_id:
          $ref: '#/components/schemas/KSUID'
        caip2:
          type: string
          description: The chain the document is for, as sent in the intent.
          example: eip155:8453
        signature:
          type: string
          description: >-
            The 65-byte signature (r, s and v) as `0x` followed by 130
            lower-case hex digits.
          pattern: ^0x[0-9a-f]{130}$
          example: >-
            0x8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f8e3f0a6c1d2b4e5f1b
        created_at:
          type: integer
          format: int64
          description: Unix time the signature was created.
          example: 1781181600
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
      description: |
        Error response following RFC 9457 Problem Details.
        Public API error responses use this format.
      example:
        type: https://docs.dakota.xyz/api-reference/errors#not-found
        title: Customer Not Found
        status: 404
        detail: Customer cst_2abc123 was not found in your organization.
        instance: https://api.platform.dakota.xyz/customers/cst_2abc123
        request_id: req_7f3a8b2c
      properties:
        type:
          type: string
          format: uri
          description: |
            URI reference identifying the problem type.
            Resolves to human-readable documentation.
          example: https://docs.dakota.xyz/api-reference/errors#not-found
        title:
          type: string
          description: >-
            Short, human-readable summary of the problem type. Stable across
            occurrences.
          example: Customer Not Found
        status:
          type: integer
          description: HTTP status code for this occurrence.
          example: 404
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: Customer cst_2abc123 was not found in your organization.
        instance:
          type: string
          format: uri
          description: The request path that triggered this error.
          example: https://api.platform.dakota.xyz/customers/cst_2abc123
        request_id:
          type: string
          description: Unique request identifier. Include when contacting support.
          example: req_7f3a8b2c
        errors:
          type: array
          description: Field-level validation errors (present for validation failures).
          items:
            $ref: '#/components/schemas/ValidationError'
        resolution_url:
          type: string
          format: uri
          description: |
            A link the customer can follow to CLEAR this error, present only on
            problems with a concrete self-service remedy.

            Today this is returned by
            `#terms-not-accepted`, where it points at the hosted flow in which
            the outstanding agreement can be signed. The link is token-gated and
            usable as-is — send the customer to it directly rather than parsing
            it out of `detail`.
          example: >-
            https://onboarding.dakota.xyz/applications/2abc123?token=tok_7f3a8b2c
        user_message:
          type: string
          description: |
            A plain-language rendition of `detail` written for the end
            customer, present when one exists for this error. `detail` names
            request fields and actions so a machine caller (such as a payment
            agent drafting proposals) can self-correct; `user_message` says the
            same thing without API vocabulary. Clients that relay errors into a
            human surface (chat, email, UI) should show `user_message` when
            present and fall back to `detail`.
          example: >-
            ACH payments pay out USD, so a USDC payout isn't possible on this
            rail. Change the payout currency to USD and try again.
        reason:
          type: string
          description: >
            A stable, machine-readable code for why the request was refused,

            present only when Dakota has a typed reason for this error. Branch

            on `reason` rather than parsing `detail`.


            When `reason` is a value from the table below other than

            `signature_required` and `immutable_field`, `detail` is text Dakota

            writes for that reason, never a partner's or a bank's wording. For

            those two, `detail` is the text written for that specific refusal.

            In every case the wording can change, so do not parse it.


            This is an open set: new values are added over time and a value is

            never repurposed, so treat an unrecognized `reason` as absent.


            Which operations return it today:


            - `createAccount` (onramp, offramp and swap) and `createTransaction`
              (a one-off transaction creates an account): every value in the
              table except `immutable_field`; `signature_required` comes from
              `createTransaction` only.
            - `updateAccount`: `field_invalid` (a developer fee that is out of
              range), `resource_not_found`, and `immutable_field` (the change
              would alter the account's routing; create a new account instead).
            - `deleteAccount`: `resource_not_found`.

            - `createWalletTransaction` and `signWalletTypedData`:
              `check_unavailable` (503) when the address screen could not run.
            - `deletePolicy`: `policy_attached` (409, under governance
              enforcement) when a wallet still holds the policy.
            - Every operation authenticated with an API key:
              `api_key_expired` (401) and `ip_not_allowed` (403).
            - `createInstructions`: a payment-agent instruction that creates an
              account fails with the same `reason` values as `createAccount`,
              but `params.field` is never returned there: the response carries
              the other `params` keys only, because this operation has no
              public field names to map to.
            - Other operations may also set `reason`. Treat a `reason` you do
              not recognize as absent, as above, and never assume an operation
              that is not listed here omits it.

            | `reason` | Meaning | `params` |

            | --- | --- | --- |

            | `field_required` | A required request field is missing. | `field`
            |

            | `field_invalid` | A field is present but unusable. | `field`,
            `constraint`, `rail` |

            | `field_too_long` | A field is longer than the rail allows. |
            `field`, `max`, `actual`, `rail` |

            | `field_too_short` | A field is shorter than the rail allows. |
            `field`, `min`, `actual` |

            | `address_incomplete` | An address lacks parts the route needs. |
            `subject`, `fields` |

            | `unsupported_network` | The network is not supported. | `network`
            |

            | `unsupported_asset` | The asset does not exist on the network. |
            `asset`, `network` |

            | `no_route_available` | No payment route covers the request. |
            `direction`, `rail`, `currency`, `network` |

            | `onboarding_required` | The customer has not completed onboarding
            for a capability. | `capability` |

            | `entity_not_active` | Onboarding for a capability exists but is
            not yet usable. | `capability`, `status` |

            | `destination_unreachable` | The destination cannot be reached over
            the requested rail. | `rail`, `alternative`, `direction` |

            | `limit_exceeded` | An amount exceeds a ceiling. | `limit`, `max`,
            `configured`, `currency` |

            | `resource_not_found` | The named resource does not exist. |
            `resource` |

            | `duplicate_resource` | A matching resource already exists. |
            `resource` |

            | `request_rejected` | The request was refused and the reason is not
            disclosed. | none |

            | `signature_required` | The request must be signed. | none |

            | `immutable_field` | The field cannot be changed on an existing
            account; create a new one. | none |

            | `endorsement_required` | The signer-group change needs signatures
            from the group's governing members. Also returned, under governance
            enforcement, when an API key creates an x402 spend mandate. Also
            returned, under governance enforcement, when an `operate` API key
            sets an account's refund wallet (`return_address` or
            `return_crypto_address`) to an address that is not one of the
            customer's saved crypto destinations on the same network: save it as
            a crypto destination first. | none |

            | `insufficient_endorsements` | The signatures do not meet the
            signer group's governance quorum (403). When `params` are present,
            the group `signer_group_id` got `have` of the `need` distinct
            governing members it requires. When they are absent, no count is
            reported; usually no signature was counted at all, because one did
            not verify over the request's intent with the key of a member of a
            group allowed to endorse it, came from a payment-agent or
            card-settlement key, or repeated a signer. | `signer_group_id`,
            `have`, `need` (all or none) |

            | `webauthn_wrong_type` | A passkey signature was not an assertion:
            its `clientDataJSON.type` is not `webauthn.get` (for example, the
            output of a registration). Sign again with
            `navigator.credentials.get` (400 `validation_error`). | none |

            | `webauthn_user_not_present` | A passkey assertion lacks the
            user-present (UP) flag, so nobody confirmed it on the authenticator
            (400 `validation_error`). | none |

            | `webauthn_user_not_verified` | A passkey assertion lacks the
            user-verified (UV) flag. Refused only where Dakota enforces user
            verification (400 `validation_error`). | none |

            | `webauthn_rp_mismatch` | A passkey is bound to a relying party ID
            that is not allowed. Refused only where Dakota enforces the RP ID
            check (400 `validation_error`). | none |

            | `webauthn_origin_mismatch` | A passkey assertion was made on an
            origin that is not allowed. Refused only where Dakota enforces the
            origin check (400 `validation_error`). | none |

            | `stale_signer_group_version` | The signer group changed since the
            signatures were made; read its `version` and sign again. | none |

            | `below_threshold` | The removal would leave the signer group below
            a threshold it must keep. | none |

            | `invalid_governing_group` | The governing signer group is missing
            or no longer valid. | none |

            | `check_unavailable` | A required safety check could not run, so
            nothing was sent; retry later with the same idempotency key. | none
            |

            | `api_key_expired` | The API key is past its `expires_at` (401).
            Use a current key. | none |

            | `ip_not_allowed` | The request came from an address outside the
            API key's `allowed_cidrs` (403). | none |

            | `session_required` | Only a person's own signed-in session may do
            this; an API key cannot. Nothing was changed. | none |

            | `unmeetable_signer_groups` | Governance enforcement cannot be
            turned on while the listed signer groups could never be governed
            under it. Nothing was changed. | none |

            | `policy_attached` | Under governance enforcement, a policy still
            attached to a wallet cannot be deleted (409). Nothing was changed.
            Detach it from each wallet first. `wallet_ids` lists up to 20 of the
            wallets, comma-separated; `wallet_count` is the total. |
            `wallet_ids`, `wallet_count` |
          example: field_too_long
        code:
          type: string
          description: |
            A stable snake_case error code for the signer-group governance
            refusals, equal to `reason` for them: `endorsement_required`,
            `insufficient_endorsements`, `stale_signer_group_version`,
            `below_threshold`, `invalid_governing_group` and `policy_attached`,
            and the passkey refusals of a signed request (`webauthn_wrong_type`,
            `webauthn_user_not_present`, `webauthn_user_not_verified`,
            `webauthn_rp_mismatch` and `webauthn_origin_mismatch`, on a 400
            `validation_error`). Absent for every other problem.
          example: insufficient_endorsements
        params:
          type: object
          description: |
            Parameters of `reason`. Every value is a string: a number, a
            token from a closed set, or the public name of a request field
            (`field` is expressed in this operation's request body, and is
            omitted when the offending value has no public name). Never free
            text. Present only alongside `reason`, and only when the reason
            has parameters.
          additionalProperties:
            type: string
          example:
            field: payment_reference
            max: '35'
            actual: '40'
            rail: swift
    SignTypedDataIntent:
      type: object
      description: >-
        The typed-data document a wallet is asked to sign, and the chain it is
        for.
      required:
        - wallet_id
        - caip2
        - typed_data
        - idempotency_key
      properties:
        wallet_id:
          type: string
          description: The ID of the wallet that signs. It must be the wallet in the path.
        caip2:
          type: string
          description: >-
            The chain the document is for, written `eip155:<chain id>` without
            leading zeros, such as `eip155:8453`. It must be an EVM chain Dakota
            supports.
          example: eip155:8453
        typed_data:
          type: string
          maxLength: 32768
          description: >
            The EIP-712 document (`types`, `primaryType`, `domain` and
            `message`) as a JSON string,

            at most 32768 bytes. Send it exactly as your approvers signed it:
            their signatures cover

            this exact string, so any change to it, whitespace and key order
            included, makes them

            invalid.


            `domain.chainId` must equal the chain of `caip2`, and
            `domain.verifyingContract` is

            required. `domain.salt` is accepted. `EIP712Domain` may declare only
            `name` (`string`),

            `version` (`string`), `chainId` (`uint256`), `verifyingContract`
            (`address`) and `salt`

            (`bytes32`). Write numbers as plain whole numbers: `1.0` and `1e3`
            are refused. Write

            any number above 2^53 - 1 (9007199254740991) as a string. Objects
            and arrays nest at

            most 32 levels deep.
        idempotency_key:
          type: string
          description: >
            A unique key for this signature request. Must be a UUID: any other
            value is refused with a 400. A repeat with the same key and the same
            intent

            returns the stored signature. Once a signature is stored, the same
            key with a different intent returns `409`;

            before then, a different request under the same key returns `400`. A
            key is tied to your client for 24 hours,

            not to one wallet.
        context_digest:
          type: string
          description: >
            Optional opaque SHA-256d digest (base64-encoded) of an upstream
            context envelope. The

            approvers' signatures cover it, but it is never read. At most 256
            bytes, with no

            control characters; any other value is refused with a 400.
    ValidationError:
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: Field path using dot notation for nested fields.
          example: bank_account.routing_number
        message:
          type: string
          description: Human-readable description of the field error.
          example: Routing number must be exactly 9 digits
        code:
          type: string
          description: Machine-readable error code for this field.
          example: invalid_format
  parameters:
    IdempotencyKeyHeader:
      name: x-idempotency-key
      in: header
      required: true
      description: >-
        Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH
        requests.


        A key is scoped to your client, the HTTP method and the path, and is
        remembered for 24 hours after a

        successful (below 400) response. Repeating the same request (same JSON
        body, whatever the key order or

        whitespace) with the same key within that window returns the original
        response with

        `X-Idempotent-Replayed: true` instead of executing the request again.
        Using the same key on the same

        endpoint with a different body returns `422` with problem type
        `idempotency-key-reused`; the request is

        not executed. Error responses (4xx and 5xx) are not remembered, so a
        request refused for a fixable reason

        can be corrected and retried under the same key. Request bodies that are
        not JSON (for example file

        uploads) are not compared.
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.