The Modern Treasury Java SDK provides convenient access to the Modern Treasury REST API from applications written in Java. It includes helper classes with helpful types and documentation for every request and response property.

The Modern Treasury Java SDK is similar to the Modern Treasury Kotlin SDK but with minor differences that make it more ergonomic for use in Java, such as Optional instead of nullable values, Stream instead of Sequence, and CompletableFuture instead of suspend functions.

The REST API documentation can be found on docs.moderntreasury.com.

implementation("com.moderntreasury:modern-treasury-java:2.22.0")

<dependency>
    <groupId>com.moderntreasury</groupId>
    <artifactId>modern-treasury-java</artifactId>
    <version>2.22.0</version>
</dependency>

Use ModernTreasuryOkHttpClient.builder() to configure the client. At a minimum you need to set .apiKey() and .organizationId():

import com.moderntreasury.api.client.ModernTreasuryClient;
import com.moderntreasury.api.client.okhttp.ModernTreasuryOkHttpClient;

ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder()
    .apiKey("My API Key")
    .organizationId("my-organization-ID")
    .build();

Alternately, set the environment with MODERN_TREASURY_API_KEY, MODERN_TREASURY_ORGANIZATION_ID or MODERN_TREASURY_WEBHOOK_KEY, and use ModernTreasuryOkHttpClient.fromEnv() to read from the environment.

ModernTreasuryClient client = ModernTreasuryOkHttpClient.fromEnv();

// Note: you can also call fromEnv() from the client builder, for example if you need to set additional properties
ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder()
    .fromEnv()
    // ... set properties on the builder
    .build();

Read the documentation for more configuration options.

To create a new counterparty, first use the CounterpartyCreateParams builder to specify attributes, then pass that to the create method of the counterparties service.

import com.moderntreasury.api.models.Counterparty;
import com.moderntreasury.api.models.CounterpartyCreateParams;

CounterpartyCreateParams params = CounterpartyCreateParams.builder()
    .name("my first counterparty")
    .build();
Counterparty counterparty = client.counterparties().create(params);

The Modern Treasury API provides a list method to get a paginated list of counterparties. You can retrieve the first page by:

import com.moderntreasury.api.models.Counterparty;
import com.moderntreasury.api.models.Page;

CounterpartyListPage page = client.counterparties().list();
for (Counterparty counterparty : page.items()) {
    System.out.println(counterparty);
}

See Pagination below for more information on transparently working with lists of objects without worrying about fetching each page.

To make a request to the Modern Treasury API, you generally build an instance of the appropriate Params class.

In Example: creating a resource above, we used the CounterpartyCreateParams.builder() to pass to the create method of the counterparties service.

Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using the putAdditionalProperty method.

import com.moderntreasury.api.models.core.JsonValue;
CounterpartyCreateParams params = CounterpartyCreateParams.builder()
    // ... normal properties
    .putAdditionalProperty("secret_param", JsonValue.from("4242"))
    .build();

When receiving a response, the Modern Treasury Java SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Java type. If you directly access the mistaken property, the SDK will throw an unchecked ModernTreasuryInvalidDataException at runtime. If you would prefer to check in advance that that response is completely well-typed, call .validate() on the returned model.

Counterparty counterparty = client.counterparties().create().validate();

In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a JsonField value.

JsonField field = responseObj._field();

if (field.isMissing()) {
  // Value was not specified in the JSON response
} else if (field.isNull()) {
  // Value was provided as a literal null
} else {
  // See if value was provided as a string
  Optional<String> jsonString = field.asString();

  // If the value given by the API did not match the shape that the SDK expects
  // you can deserialise into a custom type
  MyClass myObj = responseObj._field().asUnknown().orElseThrow().convert(MyClass.class);
}

Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's _additionalProperties method:

JsonValue secret = asyncResponse._additionalProperties().get("secret_field");

For methods that return a paginated list of results, this library provides convenient ways access the results either one page at a time, or item-by-item across all pages.

To iterate through all results across all pages, you can use autoPager, which automatically handles fetching more pages for you:

// As an Iterable:
CounterpartyListPage page = client.counterparties().list(params);
for (Counterparty counterparty : page.autoPager()) {
    System.out.println(counterparty);
};

// As a Stream:
client.counterparties().list(params).autoPager().stream()
    .limit(50)
    .forEach(counterparty -> System.out.println(counterparty));

// Using forEach, which returns CompletableFuture<Void>:
asyncClient.counterparties().list(params).autoPager()
    .forEach(counterparty -> System.out.println(counterparty), executor);

If none of the above helpers meet your needs, you can also manually request pages one-by-one. A page of results has a data() method to fetch the list of objects, as well as top-level response and other methods to fetch top-level data about the page. It also has methods hasNextPage, getNextPage, and getNextPageParams methods to help with pagination.

CounterpartyListPage page = client.counterparties().list(params);
while (page != null) {
    for (Counterparty counterparty : page.items()) {
        System.out.println(counterparty);
    }

    page = page.getNextPage().orElse(null);
}

This library throws exceptions in a single hierarchy for easy handling:

• ModernTreasuryException - Base exception for all exceptions

  • ModernTreasuryServiceException - HTTP errors with a well-formed response body we were able to parse. The exception message and the .debuggingRequestId() will be set by the server.

    400	BadRequestException
    401	AuthenticationException
    403	PermissionDeniedException
    404	NotFoundException
    422	UnprocessableEntityException
    429	RateLimitException
    5xx	InternalServerException
    others	UnexpectedStatusCodeException

  • ModernTreasuryIoException - I/O networking errors

  • ModernTreasuryInvalidDataException - any other exceptions on the client side, e.g.:

    • We failed to serialize the request body
    • We failed to parse the response body (has access to response code and body)

Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can provide a maxRetries on the client builder to configure this:

ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder()
    .fromEnv()
    .maxRetries(4)
    .build();

Requests time out after 1 minute by default. You can configure this on the client builder:

ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder()
    .fromEnv()
    .timeout(Duration.ofSeconds(30))
    .build();

Requests can be routed through a proxy. You can configure this on the client builder:

ModernTreasuryClient client = ModernTreasuryOkHttpClient.builder()
    .fromEnv()
    .proxy(new Proxy(
        Type.HTTP,
        new InetSocketAddress("proxy.com", 8080)
    ))
    .build();

This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

1. Changes to library internals which are technically public but not intended or documented for external use. (Please open a GitHub issue to let us know if you are relying on such internals).
2. Changes that we do not expect to impact the vast majority of users in practice.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.

We are keen for your feedback; please open an issue with questions, bugs, or suggestions.

This library requires Java 8 or later.