# Unified API

Source: https://docs.settlemint.com/docs/architecture/components/platform/unified-api
The Unified API provides type-safe programmatic access to all digital
asset lifecycle operations. With automatic OpenAPI generation, the API
combines type safety, comprehensive documentation, and multi-layer security
including wallet verification for blockchain transactions.




## Overview [#overview]

The Unified API exposes all DALP platform capabilities through a type-safe, documented interface. Integration engineers connect existing systems to asset lifecycle operations without understanding blockchain implementation details. Every procedure validates inputs, enforces permissions, and produces consistent responses.

Enterprise integrations demand predictable interfaces with comprehensive documentation. The Unified API delivers OpenAPI 3.1 specifications generated directly from procedure definitions, keeping the API contract visible to integration teams. Interactive exploration at `/api/v2` supports new integrations, while `/api/v2/spec.json` provides the versioned OpenAPI JSON file for client generation.

<Mermaid
  chart="`flowchart TB
  subgraph IDENTITY[&#x22;Identity layer&#x22;]
    SESSION(Session Auth)
    APIKEY(API Keys)
    SSO(Enterprise SSO)
  end

  subgraph VERIFICATION[&#x22;Transaction verification&#x22;]
    PIN(PINCODE)
    TOTP(2FA TOTP)
    CODES(Backup Codes)
  end

  subgraph API[&#x22;Unified API&#x22;]
    AUTH(Authentication Middleware)
    RBAC(Permission Check)
    PROC(Procedure Handler)
  end

  SESSION --> AUTH
  APIKEY --> AUTH
  SSO --> AUTH
  AUTH --> RBAC
  RBAC --> PROC
  PROC -.-> PIN
  PROC -.-> TOTP
  PROC -.-> CODES

  style SESSION fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style APIKEY fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style SSO fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style PIN fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style TOTP fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style CODES fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style AUTH fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style RBAC fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style PROC fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff`"
/>

## Procedure namespaces [#procedure-namespaces]

Procedures organize by domain rather than REST resource conventions. This organization reflects how operators think about platform capabilities.

| Namespace | Purpose                    | Example procedures                                 |
| --------- | -------------------------- | -------------------------------------------------- |
| `token`   | Asset lifecycle operations | Create, mint, burn, transfer, pause                |
| `user`    | User management            | List users, assign roles, manage permissions       |
| `account` | Wallet operations          | Generate address, check balance, sign transactions |
| `contact` | Investor relationships     | Register investor, record verifications            |
| `asset`   | Asset metadata             | Update documents, configure compliance rules       |
| `system`  | Platform administration    | Health checks, configuration, audit logs           |

## API design principles [#api-design-principles]

The API follows consistent design patterns across all procedures:

**Contract-first development**: Schema definitions validate all inputs before business logic executes. Changes to schemas immediately surface as errors in consuming code.

**Automatic documentation**: OpenAPI 3.1 specifications generate from procedure definitions. No manual synchronization required between implementation and documentation.

**Consistent serialization**: Complex types like large numbers, dates, and blockchain-specific values serialize correctly across the wire.

**Middleware composition**: Cross-cutting concerns like authentication, rate limiting, and audit logging apply consistently across procedure groups.

![REST API documentation for programmatic access to platform capabilities](/docs/screenshots/xvp/xvp-api-light.webp)

## Interactive documentation [#interactive-documentation]

The interactive explorer provides API exploration at `/api/v2` for the current API version. Developers authenticate, construct requests, and inspect response schemas directly from the documentation. Use `/api/v2/spec.json` when generating clients or importing the API into external tools.

## Meta-transaction support [#meta-transaction-support]

The API supports meta-transactions through the underlying ERC-2771 integration. Callers can submit signed transaction payloads without holding native tokens for gas. A configured relayer service sponsors transaction costs while the user's signature authorizes the operation.

This capability enables:

* **Simplified user experience** - Investors interact with tokens without managing cryptocurrency for fees
* **Sponsored operations** - Issuers cover transaction costs for their investors
* **Gasless workflows** - Automated systems execute transactions without native token management

Meta-transactions work transparently through the API. Callers submit signed payloads, and the platform handles relay coordination.

## Enterprise messaging integration [#enterprise-messaging-integration]

The API supports integration with enterprise financial messaging systems for institutions requiring connectivity to existing infrastructure:

* **Standards-based messaging** - Structured message formats for corporate actions, settlement instructions, and asset servicing
* **Automated reconciliation** - Outbound notifications for completed transactions enable downstream system updates
* **Audit trail synchronization** - Transaction events can trigger messages to compliance and reporting systems

These integrations connect blockchain-native operations to traditional financial infrastructure, enabling hybrid workflows where DALP handles tokenization while existing systems manage related processes.

## Error handling [#error-handling]

Errors return structured responses with consistent formats across all procedures. Error responses include machine-readable codes alongside human-readable messages.

| Category                | HTTP status | Action                         |
| ----------------------- | ----------- | ------------------------------ |
| Validation errors       | 400         | Fix request payload            |
| Authentication failures | 401         | Reauthenticate                 |
| Authorization denied    | 403         | Check role permissions         |
| Resource not found      | 404         | Verify identifier              |
| Rate limited            | 429         | Retry after delay              |
| Server errors           | 500         | Retry with exponential backoff |

Blockchain-specific errors include transaction details: gas estimation failures, revert reasons, and nonce conflicts surface as structured error responses.

## See also [#see-also]

* [Authentication](/docs/architecture/security/authentication) for identity and API key management
* [Security](/docs/architecture/security/wallet-verification) for wallet verification and rate limiting
* [Asset Console](/docs/architecture/components/platform/asset-console) for web interface
* [DALP Execution Engine](/docs/architecture/components/infrastructure/execution-engine) for operation coordination
* [API integration guide](/docs/developer-guides/api-integration/getting-started) for implementation details