Getting started

High-level view of the path to start integrating. Each step links to the corresponding concept and the real route in the API Reference.

Prefer ready-made code over building the call yourself? Use one of the official SDKs (Java, Node.js/TypeScript, Python, Go) — same API coverage, idiomatic in each language.

Building with Claude, Codex, Cursor, or another AI agent? Connect the official MCP server first (npx -y @ishtaran/mcp) — it grounds the agent in Ishtaran's real capabilities instead of letting it guess.

Quick example: check a balance

The same example (GET an Account's balance) in all 4 official languages and via plain curl — real route: GET /v1/accounts/{accountId}/balance.

Java

var client = IshtaranClient.builder()
    .apiKey(System.getenv("ISHTARAN_API_KEY"))
    .environment(Environment.SANDBOX)
    .build();

var balance = client.getBalance(accountId, assetNetworkId);
System.out.println("Available: " + balance.available());

Node.js/TypeScript

import { IshtaranClient, Environment } from '@ishtaran/sdk';

const client = IshtaranClient.create({
  apiKey: process.env.ISHTARAN_API_KEY,
  environment: Environment.Sandbox,
});

const balance = await client.getBalance(accountId, assetNetworkId);
console.log('Available:', balance.available);

Python

from ishtaran import IshtaranClient, Environment

client = IshtaranClient.create(
    api_key=os.environ["ISHTARAN_API_KEY"],
    environment=Environment.SANDBOX,
)

balance = client.get_balance(account_id, asset_network_id)
print("Available:", balance.available)

Go

client, err := ishtaran.NewClient(
	ishtaran.WithAPIKey(os.Getenv("ISHTARAN_API_KEY")),
	ishtaran.WithEnvironment(ishtaran.Sandbox),
)

balance, err := client.GetBalance(ctx, accountID, assetNetworkID)
fmt.Println("Available:", balance.Available)

cURL

curl -H "X-Api-Key: $ISHTARAN_API_KEY" \
  "https://sandbox-api.ishtaran.com/v1/accounts/$ACCOUNT_ID/balance?assetNetworkId=$ASSET_NETWORK_ID"

See the official SDKs for installation and full documentation for each, or the API Reference for the universal HTTP contract.

1. Sign up

POST /v1/auth/signup (auth.signUp() in every SDK) is the recommended way to start: one call provisions your Organization, a default Application, that Application's sandbox Environment, and a first API Key — returned once, in the response, ready to use immediately. No prior Organization/Application/Environment needs to exist yet. Always start with sandbox — no test data ever reaches production.

import { IshtaranClient, Environment } from '@ishtaran/sdk';

const owner = IshtaranClient.create({ environment: Environment.Sandbox });
const signup = await owner.auth.signUp('My Organization', 'owner@example.com', 'a-strong-password');

const client = IshtaranClient.create({ apiKey: signup.apiKeyPlainText, environment: Environment.Sandbox });

See Organization, Application and Environment for what each of these represents.

Advanced: manual/granular setup

The single signUp() call above covers a new integrator's first Organization end-to-end. Reach for the granular routes below only afterwards — to add a second Application or Environment to an Organization that already exists, to generate additional API Keys, or for other control-plane scripting. This is not the first-time onboarding path.

• POST /v1/organizations — create another Organization. See Organization.
• POST /v1/organizations/{organizationId}/applications — add another Application (your website, app, backoffice) to an existing Organization. See Application.
• POST /v1/applications/{applicationId}/environments to create an additional Environment, then POST /v1/environments/{environmentId}/api-keys to generate a further credential for it. See Environment and API Key.

2. Create your first Account

POST /v1/organizations/{organizationId}/accounts — the entity that will hold balance. See Account.

3. Create a Transaction and settle

Create the Transaction (workflowVersionId is optional — omit it entirely for your first integration) and call executeSettlement() once your own application decides the conditions are met. Settlement itself never checks Workflow state, so nothing here requires step 4 below.

4. (Optional) Define a Workflow

If you want the platform itself to model and track your business process's states instead of your own application deciding on its own, create and publish a Workflow Version that describes the release conditions, and reference its id when creating a Transaction. Skip this entirely if your own system already knows when to settle — most integrations do.

---

To simulate the entire cycle (Deposit/Withdrawal) without a real blockchain, see the Sandbox integration guide.

Prefer code over documentation? examples/quickstart-node/ (at the platform repository root) is a real Node.js script, run live before being published — it covers login, Application, Environment, API Key, Account, Transaction, Payment Intent, and crediting balance via the Sandbox Faucet, using plain fetch (no SDK). For equivalent examples using the official SDKs (Java, Node.js, Python, Go), including the same end-to-end flow, see the official SDKs — each one links to the complete example in its respective GitHub repository.

Bringing your own wallet instead of holding funds on the platform? See Self-Custody.