IWM Platform

English

Русский

English

Русский

Theme

Investment API ​

Common Information ​

Base URL ​

/api/v1/investment

Authentication Header ​

Authorization: Bearer <access_token>

Response Envelope ​

All responses follow the standard format:

typescript
// Success response
interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    pagination?: PaginationMeta;
    [key: string]: unknown;
  };
}

// Error response
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, string[]>;
  };
}

Pagination Format ​

typescript
interface PaginationMeta {
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
  hasNext: boolean;
  hasPrevious: boolean;
}

Rate Limits ​

EndpointLimit
Strategy listing/details200/min
Participation operations100/min
POST /participations3/min per user (financial)
POST /participations/:id/withdraw1/min per user (financial)
Portfolio queries100/min

Financial Endpoint Rate Limit Headers ​

X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1705329600
X-RateLimit-Policy: financial

Strategy Endpoints ​

GET /api/v1/investment/strategies ​

List investment strategies.

Authentication: Public

Rate Limit: 200 requests per minute

Request Headers ​

Authorization: Bearer <access_token>  (optional - for personalized rates)

Request Body ​

None

Query Parameters ​

ParameterTypeDescription
pagenumberPage number (optional)
pageSizenumberItems per page, max 50 (optional)
categoryIdstringFilter by category UUID (optional)
statusstringFilter: 'ACTIVE', 'PAUSED', 'CLOSED' (optional)
minAmountnumberMinimum investment amount filter (optional)
maxAmountnumberMaximum investment amount filter (optional)
minReturnnumberMinimum return percentage filter (optional)
sortBystringSort field: 'returnRate', 'duration', 'popularity', 'createdAt' (optional)
sortOrderstringSort direction: 'asc', 'desc' (optional)

Response (200 OK) ​

typescript
interface StrategiesResponse {
  strategies: Strategy[];
}

interface Strategy {
  id: string;
  name: string;
  slug: string;
  shortDescription: string;
  category: {
    id: string;
    name: string;
  };
  returnRate: {
    min: number;
    max: number;
    expected: number;
  };
  duration: {
    minDays: number;
    maxDays: number;
  };
  investment: {
    minAmount: number;
    maxAmount: number | null;
    currency: string;
  };
  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH';
  status: 'ACTIVE' | 'PAUSED' | 'CLOSED';
  popularity: {
    totalParticipants: number;
    totalInvested: number;
  };
  commissionPercentage: number;
  careerPointsPercentage: number;
  imageUrl: string | null;
  createdAt: string;
}

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORInvalid query parameters

Example ​

Request:

bash
curl -X GET "https://api.iwm-platform.com/api/v1/investment/strategies?status=ACTIVE&sortBy=returnRate&sortOrder=desc&page=1&pageSize=10"

Response:

json
{
  "success": true,
  "data": {
    "strategies": [
      {
        "id": "st0e8400-e29b-41d4-a716-446655440001",
        "name": "Growth Fund Alpha",
        "slug": "growth-fund-alpha",
        "shortDescription": "High-growth investment strategy focused on emerging markets",
        "category": {
          "id": "ic0e8400-e29b-41d4-a716-446655440001",
          "name": "Growth Funds"
        },
        "returnRate": {
          "min": 8,
          "max": 15,
          "expected": 12
        },
        "duration": {
          "minDays": 90,
          "maxDays": 365
        },
        "investment": {
          "minAmount": 10000,
          "maxAmount": 1000000,
          "currency": "RUB"
        },
        "riskLevel": "MEDIUM",
        "status": "ACTIVE",
        "popularity": {
          "totalParticipants": 1250,
          "totalInvested": 125000000
        },
        "commissionPercentage": 5,
        "careerPointsPercentage": 3,
        "imageUrl": "https://cdn.iwm-platform.com/strategies/growth-alpha.jpg",
        "createdAt": "2023-06-01T10:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 15,
      "page": 1,
      "pageSize": 10,
      "totalPages": 2,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

GET /api/v1/investment/strategies/:id ​

Get strategy details.

Authentication: Public

Rate Limit: 200 requests per minute

Request Headers ​

Authorization: Bearer <access_token>  (optional - for personalized rates)

Path Parameters ​

ParameterTypeDescription
idstring (UUID)Strategy ID

Request Body ​

None

Query Parameters ​

None

Response (200 OK) ​

typescript
interface StrategyDetailResponse {
  id: string;
  name: string;
  slug: string;
  description: string;
  shortDescription: string;
  category: {
    id: string;
    name: string;
    description: string | null;
  };
  returnRate: {
    min: number;
    max: number;
    expected: number;
    type: 'FIXED' | 'VARIABLE';
    payoutFrequency: 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'END_OF_TERM';
  };
  duration: {
    minDays: number;
    maxDays: number;
    lockPeriodDays: number;         // Early withdrawal penalty period
  };
  investment: {
    minAmount: number;
    maxAmount: number | null;
    currency: string;
    availableCapacity: number | null;
    totalCapacity: number | null;
  };
  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH';
  riskDisclosure: string;
  status: 'ACTIVE' | 'PAUSED' | 'CLOSED';
  terms: {
    earlyWithdrawalAllowed: boolean;
    earlyWithdrawalPenalty: number | null;  // Percentage
    compoundingAvailable: boolean;
    automaticReinvestment: boolean;
  };
  performance: {
    historicalReturns: {
      period: string;
      return: number;
    }[];
    averageReturn: number;
  };
  popularity: {
    totalParticipants: number;
    totalInvested: number;
    activeParticipations: number;
  };
  commissionPercentage: number;
  careerPointsPercentage: number;
  documents: {
    type: string;
    name: string;
    url: string;
  }[];
  imageUrl: string | null;
  createdAt: string;
  updatedAt: string;
}

Error Responses ​

StatusCodeDescription
404STRATEGY_NOT_FOUNDStrategy not found

Example ​

Request:

bash
curl -X GET https://api.iwm-platform.com/api/v1/investment/strategies/st0e8400-e29b-41d4-a716-446655440001

Response:

json
{
  "success": true,
  "data": {
    "id": "st0e8400-e29b-41d4-a716-446655440001",
    "name": "Growth Fund Alpha",
    "slug": "growth-fund-alpha",
    "description": "A comprehensive high-growth investment strategy focused on emerging markets...",
    "shortDescription": "High-growth investment strategy focused on emerging markets",
    "category": {
      "id": "ic0e8400-e29b-41d4-a716-446655440001",
      "name": "Growth Funds",
      "description": "Investment funds targeting capital appreciation"
    },
    "returnRate": {
      "min": 8,
      "max": 15,
      "expected": 12,
      "type": "VARIABLE",
      "payoutFrequency": "MONTHLY"
    },
    "duration": {
      "minDays": 90,
      "maxDays": 365,
      "lockPeriodDays": 30
    },
    "investment": {
      "minAmount": 10000,
      "maxAmount": 1000000,
      "currency": "RUB",
      "availableCapacity": 50000000,
      "totalCapacity": 200000000
    },
    "riskLevel": "MEDIUM",
    "riskDisclosure": "This investment carries medium risk. Past performance does not guarantee future results...",
    "status": "ACTIVE",
    "terms": {
      "earlyWithdrawalAllowed": true,
      "earlyWithdrawalPenalty": 5,
      "compoundingAvailable": true,
      "automaticReinvestment": false
    },
    "performance": {
      "historicalReturns": [
        { "period": "2023-Q4", "return": 3.2 },
        { "period": "2023-Q3", "return": 2.8 },
        { "period": "2023-Q2", "return": 3.5 },
        { "period": "2023-Q1", "return": 2.9 }
      ],
      "averageReturn": 12.4
    },
    "popularity": {
      "totalParticipants": 1250,
      "totalInvested": 125000000,
      "activeParticipations": 980
    },
    "commissionPercentage": 5,
    "careerPointsPercentage": 3,
    "documents": [
      {
        "type": "PROSPECTUS",
        "name": "Growth Fund Alpha Prospectus",
        "url": "https://cdn.iwm-platform.com/docs/gfa-prospectus.pdf"
      },
      {
        "type": "RISK_DISCLOSURE",
        "name": "Risk Disclosure Statement",
        "url": "https://cdn.iwm-platform.com/docs/gfa-risk.pdf"
      }
    ],
    "imageUrl": "https://cdn.iwm-platform.com/strategies/growth-alpha.jpg",
    "createdAt": "2023-06-01T10:00:00Z",
    "updatedAt": "2024-01-10T14:00:00Z"
  }
}

GET /api/v1/investment/categories ​

List strategy categories.

Authentication: Public

Rate Limit: 200 requests per minute

Request Headers ​

None required

Request Body ​

None

Query Parameters ​

None

Response (200 OK) ​

typescript
interface CategoriesResponse {
  categories: InvestmentCategory[];
}

interface InvestmentCategory {
  id: string;
  name: string;
  slug: string;
  description: string | null;
  imageUrl: string | null;
  strategiesCount: number;
  riskLevelRange: {
    min: 'LOW' | 'MEDIUM' | 'HIGH';
    max: 'LOW' | 'MEDIUM' | 'HIGH';
  };
  returnRange: {
    min: number;
    max: number;
  };
  isActive: boolean;
}

Error Responses ​

None specific

Example ​

Request:

bash
curl -X GET https://api.iwm-platform.com/api/v1/investment/categories

Response:

json
{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "ic0e8400-e29b-41d4-a716-446655440001",
        "name": "Growth Funds",
        "slug": "growth-funds",
        "description": "Investment funds targeting capital appreciation through emerging markets",
        "imageUrl": "https://cdn.iwm-platform.com/categories/growth.jpg",
        "strategiesCount": 5,
        "riskLevelRange": {
          "min": "MEDIUM",
          "max": "HIGH"
        },
        "returnRange": {
          "min": 8,
          "max": 20
        },
        "isActive": true
      },
      {
        "id": "ic0e8400-e29b-41d4-a716-446655440002",
        "name": "Stable Income",
        "slug": "stable-income",
        "description": "Conservative strategies focused on steady returns",
        "imageUrl": "https://cdn.iwm-platform.com/categories/stable.jpg",
        "strategiesCount": 8,
        "riskLevelRange": {
          "min": "LOW",
          "max": "MEDIUM"
        },
        "returnRange": {
          "min": 5,
          "max": 10
        },
        "isActive": true
      }
    ]
  }
}

Participation Endpoints ​

POST /api/v1/investment/participations ​

Create a new investment participation.

Authentication: Required

Rate Limit: 3 requests per minute (financial endpoint)

Request Headers ​

Authorization: Bearer <access_token>

Request Body ​

typescript
interface CreateParticipationRequest {
  strategyId: string;             // Strategy UUID
  amount: number;                 // Investment amount
  currency?: string;              // Currency (default: RUB)
  durationDays: number;           // Investment duration in days
  options?: {
    compounding?: boolean;        // Enable profit compounding
    autoReinvest?: boolean;       // Auto-reinvest at maturity
  };
  paymentMethod: 'CARD' | 'BANK_TRANSFER' | 'BALANCE';
  acceptRiskDisclosure: boolean;  // Must be true
  acceptTerms: boolean;           // Must be true
}

Query Parameters ​

None

Response (201 Created) ​

typescript
interface CreateParticipationResponse {
  participationId: string;
  strategyId: string;
  strategyName: string;
  amount: number;
  currency: string;
  durationDays: number;
  expectedReturn: {
    min: number;
    max: number;
    expected: number;
  };
  maturityDate: string;
  status: 'PENDING_PAYMENT' | 'ACTIVE';
  payment: {
    method: string;
    amount: number;
    // For card payments
    paymentUrl?: string;
    // For bank transfer
    bankDetails?: {
      bankName: string;
      accountNumber: string;
      bik: string;
      purpose: string;
    };
    expiresAt?: string;
  } | null;
  createdAt: string;
}

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORInvalid input data
400TERMS_NOT_ACCEPTEDMust accept terms and risk disclosure
400AMOUNT_BELOW_MINIMUMAmount below strategy minimum
400AMOUNT_ABOVE_MAXIMUMAmount above strategy maximum
400DURATION_INVALIDDuration outside allowed range
400INSUFFICIENT_BALANCENot enough balance (for BALANCE payment)
400STRATEGY_CAPACITY_REACHEDStrategy investment capacity full
401UNAUTHORIZEDInvalid or expired access token
403KYC_REQUIREDKYC verification required for investment
404STRATEGY_NOT_FOUNDStrategy not found
400STRATEGY_NOT_ACTIVEStrategy is not accepting investments
429RATE_LIMIT_EXCEEDEDToo many investment attempts

Example ​

Request:

bash
curl -X POST https://api.iwm-platform.com/api/v1/investment/participations \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "strategyId": "st0e8400-e29b-41d4-a716-446655440001",
    "amount": 50000,
    "durationDays": 180,
    "options": {
      "compounding": true,
      "autoReinvest": false
    },
    "paymentMethod": "CARD",
    "acceptRiskDisclosure": true,
    "acceptTerms": true
  }'

Response:

json
{
  "success": true,
  "data": {
    "participationId": "pt0e8400-e29b-41d4-a716-446655440001",
    "strategyId": "st0e8400-e29b-41d4-a716-446655440001",
    "strategyName": "Growth Fund Alpha",
    "amount": 50000,
    "currency": "RUB",
    "durationDays": 180,
    "expectedReturn": {
      "min": 4000,
      "max": 7500,
      "expected": 6000
    },
    "maturityDate": "2024-07-14",
    "status": "PENDING_PAYMENT",
    "payment": {
      "method": "CARD",
      "amount": 50000,
      "paymentUrl": "https://payment.iwm-platform.com/invest/abc123",
      "expiresAt": "2024-01-15T22:00:00Z"
    },
    "createdAt": "2024-01-15T20:00:00Z"
  }
}

GET /api/v1/investment/participations ​

List user's participations.

Authentication: Required

Rate Limit: 100 requests per minute

Request Headers ​

Authorization: Bearer <access_token>

Request Body ​

None

Query Parameters ​

ParameterTypeDescription
pagenumberPage number (optional)
pageSizenumberItems per page, max 50 (optional)
statusstringFilter: 'ACTIVE', 'PENDING_PAYMENT', 'MATURED', 'WITHDRAWN', 'CANCELLED', 'ALL' (optional)
strategyIdstringFilter by strategy UUID (optional)

Response (200 OK) ​

typescript
interface ParticipationsResponse {
  participations: Participation[];
  summary: {
    totalInvested: number;
    activeInvestments: number;
    totalReturns: number;
    pendingReturns: number;
  };
}

interface Participation {
  id: string;
  strategy: {
    id: string;
    name: string;
    slug: string;
    riskLevel: string;
  };
  amount: number;
  currency: string;
  status: 'PENDING_PAYMENT' | 'ACTIVE' | 'MATURED' | 'WITHDRAWN' | 'CANCELLED';
  returns: {
    earned: number;
    pending: number;
    projected: number;
  };
  dates: {
    startDate: string | null;
    maturityDate: string | null;
    withdrawnAt: string | null;
  };
  options: {
    compounding: boolean;
    autoReinvest: boolean;
  };
  createdAt: string;
}

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORInvalid query parameters
401UNAUTHORIZEDInvalid or expired access token

Example ​

Request:

bash
curl -X GET "https://api.iwm-platform.com/api/v1/investment/participations?status=ACTIVE&page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json
{
  "success": true,
  "data": {
    "participations": [
      {
        "id": "pt0e8400-e29b-41d4-a716-446655440001",
        "strategy": {
          "id": "st0e8400-e29b-41d4-a716-446655440001",
          "name": "Growth Fund Alpha",
          "slug": "growth-fund-alpha",
          "riskLevel": "MEDIUM"
        },
        "amount": 50000,
        "currency": "RUB",
        "status": "ACTIVE",
        "returns": {
          "earned": 1500,
          "pending": 250,
          "projected": 6000
        },
        "dates": {
          "startDate": "2024-01-15T20:05:00Z",
          "maturityDate": "2024-07-14",
          "withdrawnAt": null
        },
        "options": {
          "compounding": true,
          "autoReinvest": false
        },
        "createdAt": "2024-01-15T20:00:00Z"
      }
    ],
    "summary": {
      "totalInvested": 150000,
      "activeInvestments": 3,
      "totalReturns": 12500,
      "pendingReturns": 750
    }
  },
  "meta": {
    "pagination": {
      "total": 5,
      "page": 1,
      "pageSize": 10,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

GET /api/v1/investment/participations/:id ​

Get participation details.

Authentication: Required

Rate Limit: 100 requests per minute

Request Headers ​

Authorization: Bearer <access_token>

Path Parameters ​

ParameterTypeDescription
idstring (UUID)Participation ID

Request Body ​

None

Query Parameters ​

None

Response (200 OK) ​

typescript
interface ParticipationDetailResponse {
  id: string;
  strategy: {
    id: string;
    name: string;
    slug: string;
    riskLevel: string;
    returnRate: {
      min: number;
      max: number;
      expected: number;
    };
  };
  investment: {
    amount: number;
    currency: string;
    currentValue: number;
  };
  status: 'PENDING_PAYMENT' | 'ACTIVE' | 'MATURED' | 'WITHDRAWN' | 'CANCELLED';
  returns: {
    earned: number;
    pending: number;
    projected: number;
    rate: number;                   // Annualized return rate
  };
  dates: {
    createdAt: string;
    paymentReceivedAt: string | null;
    startDate: string | null;
    maturityDate: string | null;
    withdrawnAt: string | null;
  };
  options: {
    compounding: boolean;
    autoReinvest: boolean;
  };
  transactions: {
    id: string;
    type: 'INVESTMENT' | 'RETURN' | 'WITHDRAWAL' | 'PENALTY';
    amount: number;
    status: string;
    createdAt: string;
  }[];
  withdrawal: {
    canWithdraw: boolean;
    penaltyPercentage: number | null;
    estimatedAmount: number;
    lockPeriodEndsAt: string | null;
  };
  payment: {
    method: string;
    transactionId: string | null;
    status: string;
  } | null;
}

Error Responses ​

StatusCodeDescription
401UNAUTHORIZEDInvalid or expired access token
404PARTICIPATION_NOT_FOUNDParticipation not found

Example ​

Request:

bash
curl -X GET https://api.iwm-platform.com/api/v1/investment/participations/pt0e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json
{
  "success": true,
  "data": {
    "id": "pt0e8400-e29b-41d4-a716-446655440001",
    "strategy": {
      "id": "st0e8400-e29b-41d4-a716-446655440001",
      "name": "Growth Fund Alpha",
      "slug": "growth-fund-alpha",
      "riskLevel": "MEDIUM",
      "returnRate": {
        "min": 8,
        "max": 15,
        "expected": 12
      }
    },
    "investment": {
      "amount": 50000,
      "currency": "RUB",
      "currentValue": 51750
    },
    "status": "ACTIVE",
    "returns": {
      "earned": 1500,
      "pending": 250,
      "projected": 6000,
      "rate": 11.8
    },
    "dates": {
      "createdAt": "2024-01-15T20:00:00Z",
      "paymentReceivedAt": "2024-01-15T20:05:00Z",
      "startDate": "2024-01-15T20:05:00Z",
      "maturityDate": "2024-07-14",
      "withdrawnAt": null
    },
    "options": {
      "compounding": true,
      "autoReinvest": false
    },
    "transactions": [
      {
        "id": "tx0e8400-e29b-41d4-a716-446655440001",
        "type": "INVESTMENT",
        "amount": 50000,
        "status": "COMPLETED",
        "createdAt": "2024-01-15T20:05:00Z"
      },
      {
        "id": "tx0e8400-e29b-41d4-a716-446655440002",
        "type": "RETURN",
        "amount": 500,
        "status": "COMPLETED",
        "createdAt": "2024-02-15T00:00:00Z"
      },
      {
        "id": "tx0e8400-e29b-41d4-a716-446655440003",
        "type": "RETURN",
        "amount": 525,
        "status": "COMPLETED",
        "createdAt": "2024-03-15T00:00:00Z"
      },
      {
        "id": "tx0e8400-e29b-41d4-a716-446655440004",
        "type": "RETURN",
        "amount": 475,
        "status": "COMPLETED",
        "createdAt": "2024-04-15T00:00:00Z"
      }
    ],
    "withdrawal": {
      "canWithdraw": true,
      "penaltyPercentage": null,
      "estimatedAmount": 51750,
      "lockPeriodEndsAt": "2024-02-14T20:05:00Z"
    },
    "payment": {
      "method": "CARD",
      "transactionId": "TXN-INV-2024011500001",
      "status": "COMPLETED"
    }
  }
}

POST /api/v1/investment/participations/:id/withdraw ​

Request early withdrawal from a participation.

Authentication: Required

Rate Limit: 1 request per minute (financial endpoint)

Request Headers ​

Authorization: Bearer <access_token>

Path Parameters ​

ParameterTypeDescription
idstring (UUID)Participation ID

Request Body ​

typescript
interface WithdrawRequest {
  withdrawalMethod: 'BANK_CARD' | 'BANK_TRANSFER' | 'BALANCE';
  // Use saved payout details or provide new ones
  useSavedDetails?: boolean;
  details?: {
    cardNumber?: string;
    bankName?: string;
    bankBik?: string;
    accountNumber?: string;
  };
  acceptPenalty?: boolean;        // Required if penalty applies
}

Query Parameters ​

None

Response (200 OK) ​

typescript
interface WithdrawResponse {
  participationId: string;
  withdrawalId: string;
  status: 'PROCESSING';
  amounts: {
    principal: number;
    earnedReturns: number;
    penalty: number | null;
    netAmount: number;
    currency: string;
  };
  estimatedCompletion: string;
  message: string;
}

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORInvalid input data
400PENALTY_NOT_ACCEPTEDMust accept penalty for early withdrawal
400WITHDRAWAL_NOT_ALLOWEDStrategy does not allow early withdrawal
400LOCK_PERIOD_ACTIVECannot withdraw during lock period
401UNAUTHORIZEDInvalid or expired access token
403KYC_REQUIREDKYC verification required for withdrawal
404PARTICIPATION_NOT_FOUNDParticipation not found
400ALREADY_WITHDRAWNParticipation already withdrawn
400ALREADY_MATUREDParticipation already matured
429RATE_LIMIT_EXCEEDEDToo many withdrawal attempts

Example ​

Request:

bash
curl -X POST https://api.iwm-platform.com/api/v1/investment/participations/pt0e8400-e29b-41d4-a716-446655440001/withdraw \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "withdrawalMethod": "BALANCE",
    "acceptPenalty": false
  }'

Response:

json
{
  "success": true,
  "data": {
    "participationId": "pt0e8400-e29b-41d4-a716-446655440001",
    "withdrawalId": "wd0e8400-e29b-41d4-a716-446655440001",
    "status": "PROCESSING",
    "amounts": {
      "principal": 50000,
      "earnedReturns": 1750,
      "penalty": null,
      "netAmount": 51750,
      "currency": "RUB"
    },
    "estimatedCompletion": "2024-01-18",
    "message": "Withdrawal request submitted. Funds will be available within 3 business days."
  }
}

Portfolio Endpoints ​

GET /api/v1/investment/portfolio ​

Get portfolio summary.

Authentication: Required

Rate Limit: 100 requests per minute

Request Headers ​

Authorization: Bearer <access_token>

Request Body ​

None

Query Parameters ​

None

Response (200 OK) ​

typescript
interface PortfolioResponse {
  summary: {
    totalInvested: number;
    currentValue: number;
    totalReturns: number;
    pendingReturns: number;
    unrealizedGains: number;
    currency: string;
  };
  allocation: {
    byRiskLevel: {
      level: 'LOW' | 'MEDIUM' | 'HIGH';
      amount: number;
      percentage: number;
    }[];
    byCategory: {
      categoryId: string;
      categoryName: string;
      amount: number;
      percentage: number;
    }[];
    byStrategy: {
      strategyId: string;
      strategyName: string;
      amount: number;
      percentage: number;
      currentValue: number;
    }[];
  };
  performance: {
    overallReturn: number;        // Percentage
    annualizedReturn: number;
    bestPerforming: {
      strategyId: string;
      strategyName: string;
      return: number;
    } | null;
    worstPerforming: {
      strategyId: string;
      strategyName: string;
      return: number;
    } | null;
  };
  activeParticipations: number;
  upcomingMaturities: {
    participationId: string;
    strategyName: string;
    amount: number;
    maturityDate: string;
    expectedReturn: number;
  }[];
}

Error Responses ​

StatusCodeDescription
401UNAUTHORIZEDInvalid or expired access token

Example ​

Request:

bash
curl -X GET https://api.iwm-platform.com/api/v1/investment/portfolio \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json
{
  "success": true,
  "data": {
    "summary": {
      "totalInvested": 150000,
      "currentValue": 165000,
      "totalReturns": 12500,
      "pendingReturns": 2500,
      "unrealizedGains": 15000,
      "currency": "RUB"
    },
    "allocation": {
      "byRiskLevel": [
        { "level": "LOW", "amount": 50000, "percentage": 33.33 },
        { "level": "MEDIUM", "amount": 75000, "percentage": 50 },
        { "level": "HIGH", "amount": 25000, "percentage": 16.67 }
      ],
      "byCategory": [
        { "categoryId": "ic0e8400-e29b-41d4-a716-446655440001", "categoryName": "Growth Funds", "amount": 75000, "percentage": 50 },
        { "categoryId": "ic0e8400-e29b-41d4-a716-446655440002", "categoryName": "Stable Income", "amount": 50000, "percentage": 33.33 },
        { "categoryId": "ic0e8400-e29b-41d4-a716-446655440003", "categoryName": "Aggressive Growth", "amount": 25000, "percentage": 16.67 }
      ],
      "byStrategy": [
        { "strategyId": "st0e8400-e29b-41d4-a716-446655440001", "strategyName": "Growth Fund Alpha", "amount": 50000, "percentage": 33.33, "currentValue": 55000 },
        { "strategyId": "st0e8400-e29b-41d4-a716-446655440002", "strategyName": "Stable Income Plus", "amount": 50000, "percentage": 33.33, "currentValue": 52500 },
        { "strategyId": "st0e8400-e29b-41d4-a716-446655440003", "strategyName": "Growth Fund Beta", "amount": 25000, "percentage": 16.67, "currentValue": 28500 },
        { "strategyId": "st0e8400-e29b-41d4-a716-446655440004", "strategyName": "Aggressive Growth X", "amount": 25000, "percentage": 16.67, "currentValue": 29000 }
      ]
    },
    "performance": {
      "overallReturn": 10,
      "annualizedReturn": 11.5,
      "bestPerforming": {
        "strategyId": "st0e8400-e29b-41d4-a716-446655440004",
        "strategyName": "Aggressive Growth X",
        "return": 16
      },
      "worstPerforming": {
        "strategyId": "st0e8400-e29b-41d4-a716-446655440002",
        "strategyName": "Stable Income Plus",
        "return": 5
      }
    },
    "activeParticipations": 4,
    "upcomingMaturities": [
      {
        "participationId": "pt0e8400-e29b-41d4-a716-446655440002",
        "strategyName": "Stable Income Plus",
        "amount": 50000,
        "maturityDate": "2024-02-15",
        "expectedReturn": 2500
      }
    ]
  }
}

GET /api/v1/investment/portfolio/performance ​

Get portfolio performance history.

Authentication: Required

Rate Limit: 100 requests per minute

Request Headers ​

Authorization: Bearer <access_token>

Request Body ​

None

Query Parameters ​

ParameterTypeDescription
periodstringTime period: 'WEEK', 'MONTH', 'QUARTER', 'YEAR', 'ALL' (optional)
granularitystringData granularity: 'DAY', 'WEEK', 'MONTH' (optional)

Response (200 OK) ​

typescript
interface PerformanceHistoryResponse {
  period: string;
  periodStart: string;
  periodEnd: string;
  metrics: {
    startValue: number;
    endValue: number;
    totalReturns: number;
    percentageReturn: number;
    annualizedReturn: number;
  };
  timeline: {
    date: string;
    portfolioValue: number;
    invested: number;
    returns: number;
    cumulativeReturn: number;
  }[];
  byStrategy: {
    strategyId: string;
    strategyName: string;
    startValue: number;
    endValue: number;
    returns: number;
    percentageReturn: number;
  }[];
  transactions: {
    date: string;
    type: 'INVESTMENT' | 'RETURN' | 'WITHDRAWAL';
    amount: number;
    strategyName: string;
  }[];
}

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORInvalid period or granularity
401UNAUTHORIZEDInvalid or expired access token

Example ​

Request:

bash
curl -X GET "https://api.iwm-platform.com/api/v1/investment/portfolio/performance?period=QUARTER&granularity=WEEK" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json
{
  "success": true,
  "data": {
    "period": "QUARTER",
    "periodStart": "2023-10-15T00:00:00Z",
    "periodEnd": "2024-01-15T23:59:59Z",
    "metrics": {
      "startValue": 100000,
      "endValue": 165000,
      "totalReturns": 12500,
      "percentageReturn": 12.5,
      "annualizedReturn": 50
    },
    "timeline": [
      { "date": "2023-10-15", "portfolioValue": 100000, "invested": 100000, "returns": 0, "cumulativeReturn": 0 },
      { "date": "2023-10-22", "portfolioValue": 101200, "invested": 100000, "returns": 1200, "cumulativeReturn": 1.2 },
      { "date": "2023-10-29", "portfolioValue": 102500, "invested": 100000, "returns": 2500, "cumulativeReturn": 2.5 },
      { "date": "2023-11-05", "portfolioValue": 152800, "invested": 150000, "returns": 2800, "cumulativeReturn": 1.87 }
    ],
    "byStrategy": [
      {
        "strategyId": "st0e8400-e29b-41d4-a716-446655440001",
        "strategyName": "Growth Fund Alpha",
        "startValue": 50000,
        "endValue": 55000,
        "returns": 5000,
        "percentageReturn": 10
      },
      {
        "strategyId": "st0e8400-e29b-41d4-a716-446655440002",
        "strategyName": "Stable Income Plus",
        "startValue": 50000,
        "endValue": 52500,
        "returns": 2500,
        "percentageReturn": 5
      }
    ],
    "transactions": [
      { "date": "2023-10-15", "type": "INVESTMENT", "amount": 100000, "strategyName": "Growth Fund Alpha" },
      { "date": "2023-11-01", "type": "INVESTMENT", "amount": 50000, "strategyName": "Stable Income Plus" },
      { "date": "2023-11-15", "type": "RETURN", "amount": 500, "strategyName": "Growth Fund Alpha" },
      { "date": "2023-12-15", "type": "RETURN", "amount": 525, "strategyName": "Growth Fund Alpha" }
    ]
  }
}