Stage 4: Account Management

Account management is the final stage of conformance testing, focusing on the core evaluation account lifecycle. This stage validates your integration’s ability to create, manage, and reset evaluation accounts.

Overview

The account management stage ensures your application can:

• Create evaluation accounts with proper configuration
• Manage trading permissions and risk settings
• Handle account resets and state management
• Implement proper risk category management

Required Tests

1. Account Creation & Trading Permission

Endpoint: POST /user/createevaluationaccounts

1
{
2
  "results": [
3
    {
4
      "errorText": "string",
5
      "accountId": 1,
6
      "tradingPermissionId": 1
7
    }
8
  ],
9
  "errorText": "string"
10
}

Purpose: Create evaluation accounts and assign trading permissions to users.

Test Steps:

1. Create a single evaluation account
2. Create multiple accounts in batch (up to 100)
3. Assign trading permissions to users
4. Configure risk parameters and limits
5. Verify account creation and permission assignment

Account Creation:

1
const accountData = {
2
  userId: 12345,
3
  name: "MYFIRMEVAL00001",
4
  templateAccountId: 12345,
5
  initialBalance: 100000, // $100,000
6
  preTradeRisk: [
7
    // userAccountPositionLimits, in most cases templateAccountId will be all you need
8
  ],
9
  postTradeRisk: {
10
    trailingMaxDrawdown: 5000, //max loss, trailing up with profit.
11
    trailingMaxDrawdownLimit: 100100, //value that trailing behavior stops
12
    dailyLossAutoLiq: 500, //auto-liq after an account loses $500 in a day
13
    doNotUnlock: true, //when true, even dailyLossAutoLiq will lock the account indefinitely
14
  },
15
};
16
17
const response = await fetch("https://demo.tradovateapi.com/v1/user/createevaluationaccounts", {
18
  method: "POST",
19
  headers: {
20
    Authorization: `Bearer ${accessToken}`,
21
    "Content-Type": "application/json",
22
    Accept: "application/json",
23
  },
24
  body: JSON.stringify({ accounts: [accountData] }),
25
});

Expected Response:

1
{
2
  "results": [{ "accountId": 23456, "tradingPermissionId": 34567 }]
3
}

Error Responses:

1
{
2
  "violations": [
3
    /*string array of human-readable violations*/
4
  ]
5
}

1
{
2
  "errorText": "" // human readable error text
3
}

Validation Criteria:

• ✅ Accounts are created successfully
• ✅ Trading permissions are assigned correctly
• ✅ Risk parameters are applied properly
• ✅ Batch creation works for multiple accounts
• ✅ Account data is stored correctly
• ✅ Response time is under 10 seconds for single account
• ✅ Response time is under 60 seconds for batch creation

2. Trading Permission Revocation

Endpoint: POST /user/revoketradingpermission

1
{
2
  "errorText": "string",
3
  "tradingPermission": {
4
    "userId": 1,
5
    "accountId": 1,
6
    "accountHolderContact": "string",
7
    "accountHolderEmail": "string",
8
    "ctaContact": "string",
9
    "ctaEmail": "string",
10
    "status": "Accepted",
11
    "id": 1,
12
    "updated": "2024-01-15T09:30:00Z",
13
    "approvedById": 1
14
  }
15
}

Purpose: Revoke trading permissions from accounts.

Test Steps:

1. Revoke trading permission from active account
2. Verify permission revocation is immediate
3. Test partial permission revocation
4. Verify account access is properly restricted
5. Test error handling for invalid operations

Example Implementation:

1
const response = await fetch("https://demo.tradovateapi.com/v1/user/revoketradingpermission", {
2
  method: "POST",
3
  headers: {
4
    Authorization: `Bearer ${accessToken}`,
5
    "Content-Type": "application/json",
6
    Accept: "application/json",
7
  },
8
  body: JSON.stringify({ tradingPermissionId: 34567 }),
9
});
10
11
const data = await response.json();

Expected Response:

1
{
2
  "ok": true,
3
  "errorText": "" // string containing human-readable error
4
}

Error Response:

1
{
2
  "ok": false,
3
  "errorText": "Trading permission not found"
4
}

Bulk Permission Revocation:

1
const res = await fetch("https://demo.tradovateapi.com/v1/user/revoketradingpermissions", {
2
  method: "POST",
3
  headers: {
4
    Authorization: `Bearer ${accessToken}`,
5
    "Content-Type": "application/json",
6
    Accept: "application/json",
7
  },
8
  body: JSON.stringify({ tradingPermissionIds: [12345, 23456, 34567] }),
9
});
10
11
const data = await res.json();

Expected Response:

1
{
2
  "ok": true,
3
  "errorText": "" // string containing human-readable error
4
}

Error Response:

1
{
2
  "ok": false,
3
  "errorText": "" // string containing human-readable error
4
}

Validation Criteria:

• ✅ Trading permissions are revoked successfully
• ✅ Revocation is immediate and effective
• ✅ Account access is properly restricted
• ✅ Bulk revocation works correctly
• ✅ Error handling works for invalid operations
• ✅ Audit trail is maintained

3. Risk Category Management

Purpose: Manage and update account risk categories.

Test Steps:

1. Get available risk categories using /riskCategory/list
2. Switch account risk category using /accountRiskStatus/switchRiskCategory
3. Verify risk parameters are updated
4. Test risk category validation
5. Verify risk limits are enforced
6. Test risk category transitions

Example Implementation:

1
// First, get available risk categories
2
async function getRiskCategories() {
3
  const response = await fetch("https://demo.tradovateapi.com/v1/riskCategory/list", {
4
    headers: {
5
      Authorization: "Bearer " + accessToken,
6
      Accept: "application/json",
7
    },
8
  });
9
10
  return await response.json();
11
}

1
async function switchRiskCategory(accountIds, newRiskCategory) {
2
  // Switch risk category
3
  const switchData = {
4
    accountIds: accountIds,
5
    riskCategoryId: getRiskCategoryId(newRiskCategory),
6
  };
7
8
  const response = await fetch(
9
    "https://demo.tradovateapi.com/v1/accountRiskStatus/switchRiskCategory",
10
    {
11
      method: "POST",
12
      headers: {
13
        Authorization: "Bearer " + accessToken,
14
        "Content-Type": "application/json",
15
        Accept: "application/json",
16
      },
17
      body: JSON.stringify(switchData),
18
    }
19
  );
20
21
  return await response.json();
22
}

Expected Response:

1
{
2
  "ok": true
3
}

Error Response:

1
{
2
  "ok": false,
3
  "errorText": "" // string containing human-readable error
4
}

Validation Criteria:

• ✅ Risk categories are updated successfully
• ✅ Risk parameters are applied correctly
• ✅ Risk limits are enforced immediately
• ✅ Invalid risk categories are rejected
• ✅ Risk transitions are logged properly

4. Halt Trading for Risk Category

Endpoint: POST /accountRiskStatus/setDemoHalt

Purpose: Halt or resume trading for a specific risk category. This allows you to temporarily disable trading for specific account types or halt all trading in emergency situations.

Test Steps:

1. Get available risk categories using /riskCategory/list
2. Halt trading for a specific risk category
3. Verify trading is halted for accounts in that category
4. Resume trading for the risk category
5. Verify trading is restored for accounts in that category
6. Test emergency halt functionality

Example Implementation:

1
// First, get available risk categories
2
async function getRiskCategories() {
3
  const response = await fetch("https://demo.tradovateapi.com/v1/riskCategory/list", {
4
    headers: {
5
      Authorization: "Bearer " + accessToken,
6
      Accept: "application/json",
7
    },
8
  });
9
10
  return await response.json();
11
}
12
13
// Halt or resume trading for a risk category
14
async function setDemoHalt(riskCategoryId, halt) {
15
  const haltData = {
16
    halt,
17
    riskCategoryId,
18
  };
19
20
  const response = await fetch("https://demo.tradovateapi.com/v1/accountRiskStatus/setDemoHalt", {
21
    method: "POST",
22
    headers: {
23
      Authorization: "Bearer " + accessToken,
24
      "Content-Type": "application/json",
25
      Accept: "application/json",
26
    },
27
    body: JSON.stringify(haltData),
28
  });
29
30
  return await response.json();
31
}
32
33
// Example usage
34
async function haltTradingForCategory(riskCategoryId) {
35
  return await setDemoHalt(riskCategoryId, true);
36
}
37
38
async function resumeTradingForCategory(riskCategoryId) {
39
  return await setDemoHalt(riskCategoryId, false);
40
}

Expected Response for Risk Category List:

1
[
2
  {
3
    "id": 137,
4
    "name": "ATO-20K",
5
    "organizationId": 26
6
  },
7
  {
8
    "id": 136,
9
    "name": "ATO-50K",
10
    "organizationId": 26
11
  }
12
  //...
13
]

Expected Response for Halt Trading:

1
{
2
  "ok": true
3
}

Error Response:

1
{
2
  "ok": false,
3
  "errorText": "Invalid risk category ID or insufficient permissions"
4
}

Validation Criteria:

• ✅ Trading can be halted for specific risk categories
• ✅ Trading can be resumed for specific risk categories
• ✅ Halt status is applied immediately
• ✅ All accounts in the risk category are affected
• ✅ Emergency halt functionality works correctly
• ✅ Error handling works for invalid operations
• ✅ Audit trail is maintained for halt operations

Important Notes:

• This function allows you to temporarily disable trading for specific account types
• Use this for emergency situations or to temporarily turn off product types
• Note: Please favor the riskTimePeriod-based method over the Category Halt method when possible
• Contact Evaluation Services dev support team if you don’t have Risk Categories associated with your organization

5. Account Reset

Endpoint: POST /account/resetdemoaccountstate

1
{
2
  "ok": true,
3
  "errorText": "string"
4
}

Purpose: Reset evaluation accounts to initial state.

Test Steps:

1. Reset account to initial state
2. Verify all positions are closed
3. Verify all orders are cancelled
4. Verify balance is reset to initial amount
5. Verify account is ready for new evaluation

Example Implementation:

1
async function resetAccounts(accountIds) {
2
  // Then reset the account state
3
  const resetResponse = await fetch(
4
    "https://demo.tradovateapi.com/v1/account/resetdemoaccountstate",
5
    {
6
      method: "POST",
7
      headers: {
8
        Authorization: `Bearer ${accessToken}`,
9
        "Content-Type": "application/json",
10
        Accept: "application/json",
11
      },
12
      body: JSON.stringify({
13
        accountIds,
14
      }),
15
    }
16
  );
17
18
  return await resetResponse.json();
19
}

Expected Response:

1
{
2
  "ok": true,
3
  "errorText": ""
4
}

Error Response:

1
{
2
  "ok": false,
3
  "errorText": "Account not found or cannot be reset"
4
}

Validation Criteria:

• ✅ Account is reset to initial state
• ✅ All positions are closed
• ✅ All orders are cancelled
• ✅ Balance is reset to initial amount
• ✅ Account is ready for new evaluation
• ✅ Reset operation is logged
• ✅ Bulk reset works correctly

Error Handling

Common Error Scenarios

Account Not Found (404):

1
{
2
  "error": "Account not found",
3
  "message": "The specified account does not exist"
4
}

Security Considerations

1. Access Control: Implement proper authorization for all account operations
2. Audit Logging: Log all account management operations
3. Data Integrity: Ensure account data consistency
4. Risk Validation: Validate all risk parameters before application

Testing Checklist

• Single account creation works correctly
• Batch account creation works for multiple accounts
• Trading permissions are assigned properly
• Permission revocation works correctly
• Risk category management functions properly
• Halt trading for risk category works correctly
• Resume trading for risk category works correctly
• Account reset works as expected
• Risk limits are enforced correctly
• Error handling is robust
• Performance requirements are met
• Security requirements are satisfied
• Audit logging is complete

Conformance Completion

After completing all four stages of conformance testing:

1. Documentation: Compile test results and logs
2. Review: Submit results to solutions engineering team
3. Certification: Receive conformance certification
4. Production Access: Gain access to production environment
5. Ongoing Compliance: Maintain compliance through regular testing

Next Steps

After completing Stage 4 account management tests, you have completed all conformance testing requirements. Submit your test results and logs to the solutions engineering team for review and production access approval.

For ongoing compliance and re-certification requirements, refer to the Conformance Testing Overview.