Wallet Service

Manages wallets associated with accounts.

---

Endpoints

---

Get All Wallets

GET /wallets

Retrieve all wallet addresses available for monitoring for the authenticated participant.

Success Response

Returns a list of wallet addresses.

{
  "data": [
    {
      "participantId": "12345",
      "address": "0xabc123...",
      "blockchain": "Ethereum",
      "routerData": { "key": "value" }
    }
    // ...more wallets
  ],
  "warning": "Rails service unavailable, showing only internal data"
}

Error Responses

• 500 Internal Server Error: Failed to retrieve wallet addresses

---

Create or Get Token Account for Wallet

POST /wallets/:id/token-account

Create or get a token account for a wallet.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Account ID

Request Body

Field	Type	Required	Description	Example
tokenAddress	string	Yes	Token address to associate with the wallet	"So11111111111111111111111111111111111111112"
feePayerAccountId	uuid	No	Fee payer account ID (optional)	"fee-payer-account-id-123"

Example Request:

{
  "tokenAddress": "So11111111111111111111111111111111111111112",
  "feePayerAccountId": "fee-payer-account-id-123"
}

Success Response

Returns the created or retrieved token account object.

{
  "tokenAccountId": "token-account-uuid",
  "tokenAddress": "So11111111111111111111111111111111111111112",
  "feePayerAccountId": "fee-payer-account-id-123",
  "createdAt": "2025-11-18T12:34:56.789Z"
}

---

Get or Create Asset Token Account

GET /wallets/:id/token-account?network=solana&assetCode=USDC

Get or create an asset token account for a wallet.

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	Account ID

Query Parameters

Parameter	Type	Required	Description	Example
network	string	Yes	Network name (solana, ethereum)	"solana"
assetCode	string	Yes	Asset code	"USDC"

Success Response

Returns the asset token account object.

{
  "tokenAccountId": "token-account-uuid",
  "network": "solana",
  "assetCode": "USDC",
  "createdAt": "2025-11-18T12:34:56.789Z"
}

---

Find Wallet by Account and Network

GET /wallets/account/:accountId/network/:network?createIfNotExists=true

Find wallet by account ID and network, optionally creating if not exists.

Path Parameters

Parameter	Type	Required	Description	Example
accountId	uuid	Yes	Account ID	"eac6de80-8a71-4dc3-abee-240214cea9d5"
network	string	Yes	Network name (solana, ethereum)	"solana"

Query Parameters

Parameter	Type	Required	Description	Example
createIfNotExists	boolean	No	Create wallet if not exists	true

Success Response

Returns the wallet object.

{
  "walletId": "wallet-uuid-123",
  "accountId": "eac6de80-8a71-4dc3-abee-240214cea9d5",
  "network": "solana",
  "address": "So11111111111111111111111111111111111111112",
  "createdAt": "2025-11-18T12:34:56.789Z"
}

---

Error Format

All error responses follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Description of the error",
    "details": [
      {
        "field": "fieldName",
        "message": "Field-specific error message"
      }
    ]
  }
}

---

Field Descriptions

Field	Type	Description
participantId	string	Unique identifier for the participant
address	string	Wallet address
blockchain	string	Blockchain type (e.g., Ethereum, Solana)
routerData	object	Router configuration data (optional)
walletId	string	Unique identifier for the wallet
accountId	string	Account ID associated with the wallet
network	string	Network name
tokenAccountId	string	Token account ID
assetCode	string	Asset code (e.g., USDC)
feePayerAccountId	string	Fee payer account ID (optional)
createdAt	string	ISO8601 timestamp of creation

---

For DTO definitions, see wallet.dto.ts.