Asset Management API

This document describes the Asset Management endpoints for managing digital assets in Link Core.

Endpoints

Create Asset - POST /assets
List Assets - GET /assets
Get Asset - GET /assets/:id
Update Asset - PATCH /assets/:id
Delete Asset - DELETE /assets/:id

Create Asset

Creates a new digital asset in the system.

Endpoint: POST /assets

Request Body

{
  "code": "string",
  "name": "string",
  "decimalPlaces": number,
  "address": "string",
  "network": "string",
  "iso20022CurrencyCode": "string",
  "iso20022BankTransactionDomainCode": "string"
}

Field	Type	Required	Description
`code`	string	Yes	Unique asset code/ticker (e.g., "BTC", "USD")
`name`	string	Yes	Human-readable asset name (e.g., "Bitcoin")
`decimalPlaces`	number	Yes	Number of decimal places (e.g., 8 for BTC, 2 for USD)
`address`	string	Yes	Blockchain address or identifier
`network`	string	Yes	Blockchain network (e.g., "bitcoin", "ethereum", "solana")
`iso20022CurrencyCode`	string	No	ISO 20022 currency code (for fiat currencies)
`iso20022BankTransactionDomainCode`	string	No	ISO 20022 bank transaction domain code

Response

Status: 201 Created

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "code": "BTC",
  "name": "Bitcoin",
  "decimalPlaces": 8,
  "address": "native",
  "network": "bitcoin",
  "iso20022CurrencyCode": null,
  "iso20022BankTransactionDomainCode": null,
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Examples

Create Native Cryptocurrency

curl -X POST "https://api.ledgerlink.ai/v1/assets" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BTC",
    "name": "Bitcoin",
    "decimalPlaces": 8,
    "address": "native",
    "network": "bitcoin"
  }'

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "code": "BTC",
  "name": "Bitcoin",
  "decimalPlaces": 8,
  "address": "native",
  "network": "bitcoin",
  "iso20022CurrencyCode": null,
  "iso20022BankTransactionDomainCode": null,
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Create ERC-20 Token

curl -X POST "https://api.ledgerlink.ai/v1/assets" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "USDC",
    "name": "USD Coin",
    "decimalPlaces": 6,
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "network": "ethereum"
  }'

Response:

{
  "id": "234e4567-e89b-12d3-a456-426614174001",
  "code": "USDC",
  "name": "USD Coin",
  "decimalPlaces": 6,
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "network": "ethereum",
  "iso20022CurrencyCode": null,
  "iso20022BankTransactionDomainCode": null,
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": ["name must be a string", "code must be a string"],
  "error": "Bad Request"
}

Causes:

Missing required fields (name or code)
Invalid data types
Asset code already exists (must be unique)

409 Conflict

{
  "statusCode": 409,
  "message": "Asset with code 'BTC' already exists",
  "error": "Conflict"
}

List Assets

Retrieves all assets in the system.

Endpoint: GET /assets

Response

Status: 200 OK

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Bitcoin",
    "code": "BTC",
    "blockchain": "Bitcoin",
    "contractAddress": null,
    "decimals": 8,
    "metadata": {},
    "createdAt": "2025-11-20T10:30:00.000Z",
    "updatedAt": "2025-11-20T10:30:00.000Z"
  },
  {
    "id": "234e4567-e89b-12d3-a456-426614174001",
    "name": "Ethereum",
    "code": "ETH",
    "blockchain": "Ethereum",
    "contractAddress": null,
    "decimals": 18,
    "metadata": {},
    "createdAt": "2025-11-20T10:31:00.000Z",
    "updatedAt": "2025-11-20T10:31:00.000Z"
  },
  {
    "id": "345e4567-e89b-12d3-a456-426614174002",
    "name": "USD Coin",
    "code": "USDC",
    "blockchain": "Ethereum",
    "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "decimals": 6,
    "metadata": {
      "type": "stablecoin",
      "issuer": "Circle"
    },
    "createdAt": "2025-11-20T10:32:00.000Z",
    "updatedAt": "2025-11-20T10:32:00.000Z"
  }
]

Example

curl -X GET "https://api.ledgerlink.ai/v1/assets"

Notes

Returns all assets in the system
No pagination (for now)
Assets are returned in creation order by default

Get Asset

Retrieves a specific asset by ID.

Endpoint: GET /assets/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Asset UUID

Response

Status: 200 OK

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Bitcoin",
  "code": "BTC",
  "blockchain": "Bitcoin",
  "contractAddress": null,
  "decimals": 8,
  "metadata": {},
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Example

curl -X GET "https://api.ledgerlink.ai/v1/assets/123e4567-e89b-12d3-a456-426614174000"

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Asset not found",
  "error": "Not Found"
}

Update Asset

Updates an existing asset's details.

Endpoint: PATCH /assets/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Asset UUID

Request Body

{
  "name": "string",
  "code": "string",
  "blockchain": "string",
  "contractAddress": "string",
  "decimals": number,
  "metadata": {}
}

All fields are optional. Only provided fields will be updated.

Response

Status: 200 OK

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Bitcoin (Updated)",
  "code": "BTC",
  "blockchain": "Bitcoin",
  "contractAddress": null,
  "decimals": 8,
  "metadata": {
    "network": "mainnet",
    "explorer": "https://blockstream.info"
  },
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T15:45:00.000Z"
}

Examples

Update Asset Name

curl -X PATCH "https://api.ledgerlink.ai/v1/assets/123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bitcoin (BTC)"
  }'

Update Metadata

curl -X PATCH "https://api.ledgerlink.ai/v1/assets/123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "network": "mainnet",
      "explorer": "https://blockstream.info",
      "website": "https://bitcoin.org"
    }
  }'

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Asset not found",
  "error": "Not Found"
}

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input data",
  "error": "Bad Request"
}

Causes:

Invalid data types
Code conflict (if changing code to existing one)

Delete Asset

Soft deletes an asset from the system.

Endpoint: DELETE /assets/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Asset UUID

Response

Status: 200 OK

{
  "success": true,
  "message": "Asset successfully deleted"
}

Example

curl -X DELETE "https://api.ledgerlink.ai/v1/assets/123e4567-e89b-12d3-a456-426614174000"

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Asset not found",
  "error": "Not Found"
}

400 Bad Request

{
  "statusCode": 400,
  "message": "Cannot delete asset with existing balances or transactions",
  "error": "Bad Request"
}

Causes:

Asset has existing customer balances
Asset has historical transactions
Asset is referenced by other entities

Notes

This is a soft delete - the asset is marked as deleted but remains in the database
Deleted assets are excluded from list queries
Assets with active balances or transaction history cannot be deleted (integrity protection)

Asset Fields Reference

Field	Type	Description
`id`	string (UUID)	Unique asset identifier
`code`	string	Unique asset code/ticker symbol (e.g., "BTC", "USD")
`name`	string	Human-readable asset name
`decimalPlaces`	number	Number of decimal places for precision
`address`	string	Blockchain address or "native" for native assets
`network`	string	Blockchain network name (e.g., "bitcoin", "ethereum")
`iso20022CurrencyCode`	string or null	ISO 20022 currency code (for fiat)
`iso20022BankTransactionDomainCode`	string or null	ISO 20022 bank transaction domain code
`createdAt`	string (ISO 8601)	Creation timestamp
`updatedAt`	string (ISO 8601)	Last update timestamp

Asset Types

Native Cryptocurrencies

Native blockchain currencies (no contract address):

{
  "name": "Bitcoin",
  "code": "BTC",
  "blockchain": "Bitcoin",
  "contractAddress": null,
  "decimals": 8
}

Examples:

Bitcoin (BTC)
Ethereum (ETH)
Solana (SOL)

ERC-20 Tokens

Ethereum-based tokens (ERC-20 standard):

{
  "name": "USD Coin",
  "code": "USDC",
  "blockchain": "Ethereum",
  "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "decimals": 6
}

Examples:

USDC
USDT
DAI
UNI
AAVE

SPL Tokens

Solana-based tokens (SPL standard):

{
  "name": "USD Coin",
  "code": "USDC",
  "blockchain": "Solana",
  "contractAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "decimals": 6
}

Multi-Chain Assets

Same asset on different blockchains (separate asset records):

// USDC on Ethereum
{
  "name": "USD Coin (Ethereum)",
  "code": "USDC-ETH",
  "blockchain": "Ethereum",
  "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

// USDC on Solana
{
  "name": "USD Coin (Solana)",
  "code": "USDC-SOL",
  "blockchain": "Solana",
  "contractAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}

Decimal Precision

The decimals field defines the smallest divisible unit:

Asset	Decimals	Smallest Unit	Example
BTC	8	0.00000001	1 satoshi
ETH	18	0.000000000000000001	1 wei
USDC	6	0.000001	1 micro-dollar

Important: Always store and process amounts as integers in the smallest unit, then convert for display:

// Store as integer (satoshis)
const amountSatoshis = 150000000; // 1.5 BTC

// Display as decimal
const amountBTC = amountSatoshis / Math.pow(10, 8); // 1.5

Metadata Usage

The metadata field stores additional asset information:

Common Metadata Fields

{
  "metadata": {
    "type": "stablecoin",
    "issuer": "Circle",
    "network": "mainnet",
    "explorer": "https://etherscan.io/token/0xA0b8...",
    "website": "https://www.circle.com/usdc",
    "logo": "https://cdn.example.com/usdc.png",
    "description": "Fully-backed USD stablecoin",
    "isTestnet": false
  }
}

Use Cases

Display asset logos in UI
Link to block explorers
Show asset descriptions
Flag testnet vs mainnet assets
Track issuer information
Store additional configuration

Integration with Other Services

Link Quote Integration

Assets created in Link Core can be used with Link Quote for pricing:

Create asset in Link Core
Create matching asset in Link Quote (with same code)
Configure providers in Link Quote
Fetch rates using asset code

Wallet Manager Integration

Assets must be configured in both Link Core and Wallet Manager:

Link Core tracks balances and transactions
Wallet Manager handles blockchain interactions
Asset codes must match between services

Best Practices

1. Use Descriptive Names

Include blockchain or network in name for clarity:

{
  "name": "USD Coin (Ethereum)",
  "code": "USDC-ETH"
}

2. Unique Codes for Multi-Chain

Use different codes for same asset on different chains:

// Good
{ "code": "USDC-ETH", "blockchain": "Ethereum" }
{ "code": "USDC-SOL", "blockchain": "Solana" }

// Bad (duplicate codes)
{ "code": "USDC", "blockchain": "Ethereum" }
{ "code": "USDC", "blockchain": "Solana" }

3. Verify Contract Addresses

Always double-check contract addresses before creating tokens:

# Verify on blockchain explorer
# Ethereum: https://etherscan.io
# Solana: https://explorer.solana.com

4. Set Correct Decimals

Use standard decimals for known assets:

BTC: 8
ETH: 18
USDC/USDT: 6

5. Store Rich Metadata

Include all relevant information in metadata:

{
  "metadata": {
    "explorer": "https://etherscan.io/token/0x...",
    "website": "https://...",
    "logo": "https://...",
    "isTestnet": false
  }
}

Need Help? Contact helpdesk@ledgerlink.ai for assistance.

Endpoints​

Create Asset​

Request Body​

Response​

Examples​

Create Native Cryptocurrency​

Create ERC-20 Token​

Error Responses​

400 Bad Request​

409 Conflict​

List Assets​

Response​

Example​

Notes​

Get Asset​

Path Parameters​

Response​

Example​

Error Responses​

404 Not Found​

Update Asset​

Path Parameters​

Request Body​

Response​

Examples​

Update Asset Name​

Update Metadata​

Error Responses​

404 Not Found​

400 Bad Request​

Delete Asset​

Path Parameters​

Response​

Example​

Error Responses​

404 Not Found​

400 Bad Request​

Notes​

Asset Fields Reference​

Asset Types​

Native Cryptocurrencies​

ERC-20 Tokens​

SPL Tokens​

Multi-Chain Assets​

Decimal Precision​

Metadata Usage​

Common Metadata Fields​

Use Cases​

Integration with Other Services​

Link Quote Integration​

Wallet Manager Integration​

Best Practices​

1. Use Descriptive Names​

2. Unique Codes for Multi-Chain​

3. Verify Contract Addresses​

4. Set Correct Decimals​

5. Store Rich Metadata​

Endpoints

Create Asset

Request Body

Response

Examples

Create Native Cryptocurrency

Create ERC-20 Token

Error Responses

400 Bad Request

409 Conflict

List Assets

Response

Example

Notes

Get Asset

Path Parameters

Response

Example

Error Responses

404 Not Found

Update Asset

Path Parameters

Request Body

Response

Examples

Update Asset Name

Update Metadata

Error Responses

404 Not Found

400 Bad Request

Delete Asset

Path Parameters

Response

Example

Error Responses

404 Not Found

400 Bad Request

Notes

Asset Fields Reference

Asset Types

Native Cryptocurrencies

ERC-20 Tokens

SPL Tokens

Multi-Chain Assets

Decimal Precision

Metadata Usage

Common Metadata Fields

Use Cases

Integration with Other Services

Link Quote Integration

Wallet Manager Integration

Best Practices

1. Use Descriptive Names

2. Unique Codes for Multi-Chain

3. Verify Contract Addresses

4. Set Correct Decimals

5. Store Rich Metadata