Skip to content

Commit ddcd552

Browse files
author
方佳
committed
Merge branch 'main_merge_260921' into 'main'
feat: support transfers activities for Webull US See merge request webull/webull-openapi-java-sdk!48
2 parents a7ce915 + 983697f commit ddcd552

16 files changed

Lines changed: 1080 additions & 4 deletions

File tree

‎pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
<groupId>com.webull.openapi</groupId>
2222
<artifactId>webull-openapi-java-sdk-parent</artifactId>
2323
<packaging>pom</packaging>
24-
<version>2.0.1</version>
24+
<version>2.0.2</version>
2525

2626
<name>webull-openapi-java-sdk-parent</name>
2727
<url>https://github.com/webull-inc/webull-openapi-java-sdk/</url>

‎webull-openapi-java-sdk-samples/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
<parent>
2020
<groupId>com.webull.openapi</groupId>
2121
<artifactId>webull-openapi-java-sdk-parent</artifactId>
22-
<version>2.0.1</version>
22+
<version>2.0.2</version>
2323
</parent>
2424
<modelVersion>4.0.0</modelVersion>
2525

‎webull-openapi-java-sdk-samples/src/main/java/com/webull/openapi/samples/trade/TradeClientV3.java‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,13 @@
99
import com.webull.openapi.core.utils.GUID;
1010
import com.webull.openapi.core.utils.StringUtils;
1111
import com.webull.openapi.samples.config.Env;
12+
import com.webull.openapi.trade.request.TransfersActivitiesRequest;
1213
import com.webull.openapi.trade.request.v3.OptionOrderItemLeg;
1314
import com.webull.openapi.trade.request.v3.TradeOrder;
1415
import com.webull.openapi.trade.request.v3.TradeOrderItem;
16+
import com.webull.openapi.trade.response.PaginatedResult;
17+
import com.webull.openapi.trade.response.Transfer;
18+
import com.webull.openapi.trade.response.TransferDetail;
1519
import com.webull.openapi.trade.response.v3.*;
1620

1721
import java.util.ArrayList;
@@ -62,10 +66,13 @@ public static void main(String[] args) throws InterruptedException {
6266
runTrailingStopLossComboOrderExample(apiService, accountIds.getSecurityAccountIds().get(0));
6367

6468
runTrailingStopLossLimitComboOrderExample(apiService, accountIds.getSecurityAccountIds().get(0));
69+
70+
runTransfersActivitiesExample(apiService, accountIds.getSecurityAccountIds().get(0));
6571
}
6672

6773
if (CollectionUtils.isNotEmpty(accountIds.getCryptoAccountIds())) {
6874
runCryptoOrderExample(apiService, accountIds.getCryptoAccountIds().get(0));
75+
runTransfersActivitiesExample(apiService, accountIds.getCryptoAccountIds().get(0));
6976
}
7077

7178
if (CollectionUtils.isNotEmpty(accountIds.getFuturesAccountIds())) {
@@ -938,6 +945,45 @@ private static void runTouchLimitComboOrderExample(com.webull.openapi.trade.Trad
938945
logger.info("masterOrderDetailResponse: {}", masterOrderDetailResponse);
939946
}
940947

948+
private static void runTransfersActivitiesExample(com.webull.openapi.trade.TradeClientV3 apiService, String accountId) {
949+
// 1) First page: pass null for paginationKey, no filters.
950+
TransfersActivitiesRequest firstPageRequest = new TransfersActivitiesRequest();
951+
firstPageRequest.setAccountId(accountId);
952+
PaginatedResult<Transfer> firstPage = apiService.listTransfersActivities(firstPageRequest);
953+
logger.info("transfersActivitiesFirstPage: {}", firstPage);
954+
955+
// 2) Iterate all pages using the returned paginationKey until it is null.
956+
String paginationKey = firstPage == null ? null : firstPage.getPaginationKey();
957+
while (StringUtils.isNotBlank(paginationKey)) {
958+
TransfersActivitiesRequest nextPageRequest = new TransfersActivitiesRequest();
959+
nextPageRequest.setAccountId(accountId);
960+
nextPageRequest.setPaginationKey(paginationKey);
961+
PaginatedResult<Transfer> nextPage = apiService.listTransfersActivities(nextPageRequest);
962+
logger.info("transfersActivitiesNextPage: {}", nextPage);
963+
paginationKey = nextPage == null ? null : nextPage.getPaginationKey();
964+
}
965+
966+
// 3) Filtered query: ACATS incoming transfers, FULL type, within a time range.
967+
TransfersActivitiesRequest filteredRequest = new TransfersActivitiesRequest();
968+
filteredRequest.setAccountId(accountId);
969+
filteredRequest.setTransferMethod("ACATS");
970+
filteredRequest.setDirection("INCOMING");
971+
filteredRequest.setStatus("PENDING,COMPLETED");
972+
filteredRequest.setAcatsTransferTypes("FULL");
973+
filteredRequest.setStartTime("2026-08-01T00:00:00Z");
974+
filteredRequest.setEndTime("2026-08-31T23:59:59Z");
975+
PaginatedResult<Transfer> filtered = apiService.listTransfersActivities(filteredRequest);
976+
logger.info("transfersActivitiesFiltered: {}", filtered);
977+
978+
// 4) Get a single transfer record by transferId (taken from the first page when available).
979+
if (firstPage != null && CollectionUtils.isNotEmpty(firstPage.getData())
980+
&& StringUtils.isNotBlank(firstPage.getData().get(0).getTransferId())) {
981+
String transferId = firstPage.getData().get(0).getTransferId();
982+
TransferDetail transfer = apiService.getTransferActivity(accountId, transferId);
983+
logger.info("transferActivityDetail: {}", transfer);
984+
}
985+
}
986+
941987
private static void doSleep() throws InterruptedException {
942988
final int totalSeconds = 5;
943989
final int intervalSeconds = 1;

‎webull-openapi-java-sdk/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
<parent>
88
<groupId>com.webull.openapi</groupId>
99
<artifactId>webull-openapi-java-sdk-parent</artifactId>
10-
<version>2.0.1</version>
10+
<version>2.0.2</version>
1111
</parent>
1212

1313
<artifactId>webull-openapi-java-sdk</artifactId>

‎webull-openapi-java-sdk/src/main/java/com/webull/openapi/core/common/dict/OrderType.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,11 @@ public enum OrderType {
7272
*/
7373
AT_AUCTION_LIMIT,
7474

75+
/**
76+
* Odd lot limit order (Hong Kong stocks)
77+
*/
78+
ODD_LOT_LIMIT,
79+
7580
/**
7681
* Opening market order(U.S. Stock)
7782
*/

‎webull-openapi-java-sdk/src/main/java/com/webull/openapi/core/config/ProjectReaderHelper.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ private ProjectReaderHelper() {
2424

2525
private static final String APPLICATION_VERSION = "application.version";
2626

27-
private static final String DEFAULT_APPLICATION_VERSION = "2.0.1";
27+
private static final String DEFAULT_APPLICATION_VERSION = "2.0.2";
2828

2929
private static final String APPLICATION_NAME = "application.name";
3030

‎webull-openapi-java-sdk/src/main/java/com/webull/openapi/trade/TradeClientV3.java‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,21 +17,26 @@
1717
import com.webull.openapi.core.utils.StringUtils;
1818
import com.webull.openapi.trade.http.ITradeV3Client;
1919
import com.webull.openapi.trade.request.v3.*;
20+
import com.webull.openapi.trade.request.TransfersActivitiesRequest;
2021
import com.webull.openapi.trade.response.PaginatedResult;
2122
import com.webull.openapi.trade.response.TradeCalendar;
23+
import com.webull.openapi.trade.response.Transfer;
24+
import com.webull.openapi.trade.response.TransferDetail;
2225
import com.webull.openapi.trade.response.v3.*;
2326

2427
import java.util.*;
2528

2629
public class TradeClientV3 implements ITradeV3Client {
2730

2831
private static final String ACCOUNT_ID_ARG = "accountId";
32+
private static final String REQUEST_ARG = "request";
2933
private static final String TRADE_ORDER_ARG = "tradeOrder";
3034
private static final String NEW_ORDERS_ARG = "newOrders";
3135
private static final String BATCH_ORDERS_ARG = "batchOrders";
3236
private static final String MODIFY_ORDERS_ARG = "modifyOrders";
3337
private static final String CLIENT_ORDER_ID_ARG = "clientOrderId";
3438
private static final String INSTRUMENT_ID_ARG = "instrumentId";
39+
private static final String TRANSFER_ID_ARG = "transferId";
3540

3641
private static final String PAGE_SIZE_PARAM = "page_size";
3742
private static final String START_DATE_PARAM = "start_date";
@@ -58,6 +63,12 @@ public class TradeClientV3 implements ITradeV3Client {
5863

5964
private static final String LAST_EXECUTION_ID_PARAM = "last_execution_id";
6065

66+
private static final String TRANSFER_METHOD_PARAM = "transfer_method";
67+
private static final String TRANSFER_ID_PARAM = "transfer_id";
68+
private static final String DIRECTION_PARAM = "direction";
69+
private static final String STATUS_PARAM = "status";
70+
private static final String ACATS_TRANSFER_TYPES_PARAM = "acats_transfer_types";
71+
6172
private static final String PAGINATION_KEY_PARAM = "pagination_key";
6273

6374
private final Region region;
@@ -396,6 +407,52 @@ public PaginatedResult<Activity> getCashActivities(String accountId, String acti
396407
}.getType()).doAction();
397408
}
398409

410+
@Override
411+
public PaginatedResult<Transfer> listTransfersActivities(TransfersActivitiesRequest request) {
412+
assertUsRegion("listTransfersActivities");
413+
Assert.notNull(REQUEST_ARG, request);
414+
Assert.notBlank(ACCOUNT_ID_ARG, request.getAccountId());
415+
HttpRequest httpRequest = new HttpRequest("/trading/activities/transfer-activities/list", Versions.V3, HttpMethod.GET);
416+
Map<String, Object> params = new HashMap<>();
417+
params.put(ACCOUNT_ID_PARAM, request.getAccountId());
418+
if (StringUtils.isNotEmpty(request.getTransferMethod())) {
419+
params.put(TRANSFER_METHOD_PARAM, request.getTransferMethod());
420+
}
421+
if (StringUtils.isNotEmpty(request.getDirection())) {
422+
params.put(DIRECTION_PARAM, request.getDirection());
423+
}
424+
if (StringUtils.isNotEmpty(request.getStatus())) {
425+
params.put(STATUS_PARAM, request.getStatus());
426+
}
427+
if (StringUtils.isNotEmpty(request.getAcatsTransferTypes())) {
428+
params.put(ACATS_TRANSFER_TYPES_PARAM, request.getAcatsTransferTypes());
429+
}
430+
if (StringUtils.isNotEmpty(request.getStartTime())) {
431+
params.put(START_TIME_PARAM, request.getStartTime());
432+
}
433+
if (StringUtils.isNotEmpty(request.getEndTime())) {
434+
params.put(END_TIME_PARAM, request.getEndTime());
435+
}
436+
if (StringUtils.isNotEmpty(request.getPaginationKey())) {
437+
params.put(PAGINATION_KEY_PARAM, request.getPaginationKey());
438+
}
439+
httpRequest.setQuery(params);
440+
return apiClient.request(httpRequest).responseType(new TypeToken<PaginatedResult<Transfer>>() {
441+
}.getType()).doAction();
442+
}
443+
444+
@Override
445+
public TransferDetail getTransferActivity(String accountId, String transferId) {
446+
assertUsRegion("getTransferActivity");
447+
Assert.notBlank(Arrays.asList(ACCOUNT_ID_ARG, TRANSFER_ID_ARG), accountId, transferId);
448+
HttpRequest request = new HttpRequest("/trading/activities/transfer-activities/get", Versions.V3, HttpMethod.GET);
449+
Map<String, Object> params = new HashMap<>();
450+
params.put(ACCOUNT_ID_PARAM, accountId);
451+
params.put(TRANSFER_ID_PARAM, transferId);
452+
request.setQuery(params);
453+
return apiClient.request(request).responseType(TransferDetail.class).doAction();
454+
}
455+
399456
@Override
400457
public PaginatedResult<OrderExecution> getOrderExecutions(String accountId, String clientOrderId, String startDate,
401458
String endDate, String paginationKey) {
@@ -420,6 +477,14 @@ public PaginatedResult<OrderExecution> getOrderExecutions(String accountId, Stri
420477
}.getType()).doAction();
421478
}
422479

480+
private void assertUsRegion(String operation) {
481+
if (region != Region.us) {
482+
throw new ClientException(ErrorCode.NOT_SUPPORT,
483+
operation + " is currently supported only for Webull US region, current region is "
484+
+ region.name() + ".");
485+
}
486+
}
487+
423488
private void addCustomHeadersFromOrder(HttpRequest request, List<TradeOrderItem> orders) {
424489
if (CollectionUtils.isEmpty(orders)
425490
|| Objects.isNull(orders.get(0))) {

‎webull-openapi-java-sdk/src/main/java/com/webull/openapi/trade/http/ITradeV3Client.java‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
package com.webull.openapi.trade.http;
22

3+
import com.webull.openapi.trade.request.TransfersActivitiesRequest;
34
import com.webull.openapi.trade.request.v3.TradeOrder;
45
import com.webull.openapi.trade.response.PaginatedResult;
56
import com.webull.openapi.trade.response.TradeCalendar;
7+
import com.webull.openapi.trade.response.Transfer;
8+
import com.webull.openapi.trade.response.TransferDetail;
69
import com.webull.openapi.trade.response.v3.*;
710

811
import java.util.List;
@@ -175,6 +178,38 @@ List<Activity> getCashActivities(String accountId, String activityTypes, String
175178
PaginatedResult<Activity> getCashActivities(String accountId, String activityTypes, String startTime,
176179
String endTime, String paginationKey);
177180

181+
/**
182+
* List transfer records with paginationKey-based pagination.
183+
* Routes to ACATS or crypto transfer downstream by account type; results are ordered by create time descending.
184+
* Pass null for paginationKey on the first request; use the returned paginationKey for subsequent pages.
185+
* A null paginationKey in the response indicates there are no more pages.
186+
* This interface is currently supported only for Webull US.
187+
* Support for other regions will be available in future updates.
188+
*
189+
* @param request the request containing accountId (required) and optional filters:
190+
* transferMethod (comma-separated, e.g. ACATS,CRYPTO_TRANSFER),
191+
* direction (INCOMING or OUTGOING),
192+
* status (comma-separated: PENDING, COMPLETED, REJECTED, FAILED, CANCELLED),
193+
* acatsTransferTypes (comma-separated: FULL, PARTIAL, RESIDUAL, RECLAIM, OTHER),
194+
* startTime / endTime (ISO8601 UTC transfer create time range),
195+
* paginationKey (from previous response, null for first page)
196+
* @return paginated result containing transfer list and next pagination key
197+
* @throws com.webull.openapi.core.exception.ClientException if the region is not Webull US
198+
*/
199+
PaginatedResult<Transfer> listTransfersActivities(TransfersActivitiesRequest request);
200+
201+
/**
202+
* Get a single transfer record by account ID and transfer ID.
203+
* This interface is currently supported only for Webull US.
204+
* Support for other regions will be available in future updates.
205+
*
206+
* @param accountId the account ID (required)
207+
* @param transferId the transfer record ID (required)
208+
* @return the transfer detail record, including contra broker, cash and position entries
209+
* @throws com.webull.openapi.core.exception.ClientException if the region is not Webull US
210+
*/
211+
TransferDetail getTransferActivity(String accountId, String transferId);
212+
178213
/**
179214
* Get order executions with paginationKey-based pagination.
180215
* Pass null for paginationKey on the first request; use the returned paginationKey for subsequent pages.
Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
package com.webull.openapi.trade.request;
2+
3+
import java.io.Serializable;
4+
5+
public class TransfersActivitiesRequest implements Serializable {
6+
7+
private static final long serialVersionUID = 8723617558934621135L;
8+
private String accountId;
9+
private String transferMethod;
10+
private String direction;
11+
private String status;
12+
private String acatsTransferTypes;
13+
private String startTime;
14+
private String endTime;
15+
private String paginationKey;
16+
17+
public String getAccountId() {
18+
return accountId;
19+
}
20+
21+
public void setAccountId(String accountId) {
22+
this.accountId = accountId;
23+
}
24+
25+
public String getTransferMethod() {
26+
return transferMethod;
27+
}
28+
29+
public void setTransferMethod(String transferMethod) {
30+
this.transferMethod = transferMethod;
31+
}
32+
33+
public String getDirection() {
34+
return direction;
35+
}
36+
37+
public void setDirection(String direction) {
38+
this.direction = direction;
39+
}
40+
41+
public String getStatus() {
42+
return status;
43+
}
44+
45+
public void setStatus(String status) {
46+
this.status = status;
47+
}
48+
49+
public String getAcatsTransferTypes() {
50+
return acatsTransferTypes;
51+
}
52+
53+
public void setAcatsTransferTypes(String acatsTransferTypes) {
54+
this.acatsTransferTypes = acatsTransferTypes;
55+
}
56+
57+
public String getStartTime() {
58+
return startTime;
59+
}
60+
61+
public void setStartTime(String startTime) {
62+
this.startTime = startTime;
63+
}
64+
65+
public String getEndTime() {
66+
return endTime;
67+
}
68+
69+
public void setEndTime(String endTime) {
70+
this.endTime = endTime;
71+
}
72+
73+
public String getPaginationKey() {
74+
return paginationKey;
75+
}
76+
77+
public void setPaginationKey(String paginationKey) {
78+
this.paginationKey = paginationKey;
79+
}
80+
81+
@Override
82+
public String toString() {
83+
return "TransfersActivitiesRequest{" +
84+
"accountId='" + accountId + '\'' +
85+
", transferMethod='" + transferMethod + '\'' +
86+
", direction='" + direction + '\'' +
87+
", status='" + status + '\'' +
88+
", acatsTransferTypes='" + acatsTransferTypes + '\'' +
89+
", startTime='" + startTime + '\'' +
90+
", endTime='" + endTime + '\'' +
91+
", paginationKey='" + paginationKey + '\'' +
92+
'}';
93+
}
94+
95+
}

0 commit comments

Comments
 (0)