API Conventions

Cross-cutting rules that apply to all Max Capital APIs. They hold for any endpoint unless its own documentation states otherwise.

Environments

Environment	Base URL	Use
Development (sandbox)	https://openapi-dev.max.capital	Integration testing
Production	https://openapi.max.capital	Real operations, with financial impact

Within the Base URL, each service sits under its own prefix, and the endpoint path starts with the version:

Service	Prefix	Full URL (development)
Authentication (login)	/auth/api	https://openapi-dev.max.capital/auth/api/v1/login
Business endpoints	/gateway-openapi/api	https://openapi-dev.max.capital/gateway-openapi/api/v1/holdings/instruments

Credentials are environment-specific: use your development credentials against the development Base URL.

Authentication

All requests require a valid JWT token in the Authorization header, using the Bearer {token} format. The token is obtained from the login endpoint and has a limited lifetime (see Authentication).

Versioning

The API version is in the URL. The current version is v1, so all endpoints start with /v1/. Breaking changes are published under a new version; backward-compatible changes are added within the current version.

Date format

All dates use ISO 8601:

• Plain dates: YYYY-MM-DD (for example, 2025-04-01).
• Timestamps: with UTC time zone (for example, 2024-06-01T14:15:59.999Z).

Content type

Requests with a body use Content-Type: application/json and responses are returned as JSON.

Error handling

On error, the API responds with the corresponding HTTP status code and a body with this structure:

{
  "statusCode": "400",
  "errorCode": "INVALID_PARAMETER",
  "title": "Bad Request",
  "detail": "El parámetro 'dateType' es inválido."
}

Most frequent codes:

Code	Meaning
400	Invalid request (malformed parameters).
401	Invalid credentials or token.
403	No permission over the requested resource.
404	The resource does not exist.
422	The request does not meet a business rule.
500	Internal server error.

Usage limits

To protect the service, the API limits how many requests it accepts per unit of time. When the limit is exceeded, requests are rejected with the 429 status code until the rate is back within the allowance. Concrete values are agreed per integration.

How to integrate well with the limit:

• Retry with exponential backoff. Wait before the first retry and double the wait on each following attempt. Retrying in a tight loop sustains the excess and prolongs the rejection.
• Stagger batch processes. If you iterate over many account holders to reconcile or close the day, spread the requests out instead of sending them all at once.
• Avoid continuous polling. To follow the status of an operation, poll at intervals of seconds or minutes, not without pause.
• A 429 says nothing about the previous operation. If you were checking the status of something already submitted, that operation is still running: check again after waiting.

Data and currencies

Descriptive values returned by the API (for example, a currency description) come in Spanish. Currency codes depend on each API: see the corresponding section in Cuenta corriente.