📦 Official SDKs

TypeScript and Python client libraries for the Mesta API. Every published endpoint is a typed method with the parameters, responses and errors documented in this reference.

Quickstart

1. Create an API key and secret in the Merchant Portal, as described in Authentication and Authorization. Both stay on your servers. Never ship them in a browser or a mobile app.
2. Install the library and create a client that reads the credentials from your environment.
3. Make a call. The example below asks for a quote from USDC on Solana to euros. A quote is a price, it moves no money, so it is a safe first request. On staging, test tokens let you go further.

import { MestaClient, MestaEnvironment } from "@mestafi/sdk";

const client = new MestaClient({
  apiKey: process.env.MESTA_API_KEY!,
  apiSecret: process.env.MESTA_API_SECRET!,
  environment: MestaEnvironment.Staging, // Production is the default
});

const quote = await client.quotes.create({
  sourceCurrency: "USDC_SOL",
  targetCurrency: "EUR",
  sourceAmount: 10,
});

console.log(quote.data);

import os

from mesta import Mesta, MestaEnvironment

client = Mesta(
    api_key=os.environ["MESTA_API_KEY"],
    api_secret=os.environ["MESTA_API_SECRET"],
    environment=MestaEnvironment.STAGING,  # PRODUCTION is the default
)

quote = client.quotes.create(
    source_currency="USDC_SOL",
    target_currency="EUR",
    source_amount=10,
)

print(quote.data)

Every reference page in this documentation shows the same call in both languages under TypeScript SDK and Python SDK in the code panel.

Environments

Production, https://api.mesta.xyz, is the default. Staging, https://api.stg.mesta.xyz, is selected with MestaEnvironment.Staging in TypeScript or MestaEnvironment.STAGING in Python. Each environment has its own API keys, created in its own portal.

Authentication

The client sends the API key and secret as the x-api-key and x-api-secret headers on every request. Permissions are scoped per key when you create it; a call outside the key's scope fails with a 403. The libraries never write the credentials to their own logs.

Errors

A response outside the 2xx range raises a typed error carrying the HTTP status and the response body, so you can branch on the class instead of parsing text. The classes, with the status they map to, are BadRequestError (400), UnauthorizedError (401), ForbiddenError (403), NotFoundError (404), ConflictError (409), TooManyRequestsError (429) and InternalServerError (500). Every other status raises the base class, MestaError in TypeScript and ApiError in Python. The meaning of each code in the body is in Error codes.

import { MestaError, Mesta } from "@mestafi/sdk";

try {
  await client.beneficiaries.get({ id: "..." });
} catch (err) {
  if (err instanceof Mesta.NotFoundError) {
    // no such beneficiary
  } else if (err instanceof MestaError) {
    console.error(err.statusCode, err.body);
  } else {
    throw err;
  }
}

from mesta.core.api_error import ApiError
from mesta.errors import NotFoundError

try:
    client.beneficiaries.get(id="...")
except NotFoundError:
    ...  # no such beneficiary
except ApiError as e:
    print(e.status_code, e.body)

Retries, timeouts and writes

By default a request is retried up to two times, with exponential backoff and jitter, on 408, 429 and 5xx responses (Python also retries 409). A Retry-After header from the API is honoured, which is how rate limits are handled for you. The default timeout is 60 seconds. Both can be set on the client or on a single call.

const order = await client.orders.create(
  { /* ... */ },
  { maxRetries: 0, timeoutInSeconds: 30 },
);

order = client.orders.create(
    # ...
    request_options={"max_retries": 0, "timeout": 30},
)

Pagination

List methods take page and pageSize in TypeScript, page and page_size in Python, and return one page per call, exactly as described in Pagination. The libraries do not fetch following pages on their own.

Webhooks

The libraries send requests; they do not receive webhooks. Verify each delivery as described in Webhook signature verification, and see Webhook events for the payloads.

Versions and support

Both libraries follow semantic versioning. While the major version is 0, a minor release may change a method signature, so pin the exact version in production and read the release notes before upgrading. Report a problem as an issue on the library's repository, or write to [email protected].

For AI coding agents

Each repository's reference.md lists every method with a runnable example, and this documentation is available as plain text at docs.mesta.xyz/llms.txt. Point an agent at both and it can write a correct integration without guessing method names.

Next: TypeScript SDK and Python SDK for client options, raw responses, async use and logging.