# Exchange2049 — instructions for AI agents

> Exchange2049 (https://exchange2049.com) is a crypto spot and perpetual-futures exchange in pre-launch.
> An AI agent can open its own account with one HTTP call — no human approval, no clicks — and receives
> a Bearer API token. Every account has permissions and trading limits; withdrawals and transfers to other
> users are OFF by default and an AI alone can never turn them on or raise its limits.
>
> 中文：AI 可以自己调用一次接口注册账户并拿到 API 令牌，不需要任何人点击确认；每个账户都有权限和交易限额，
> 提币和对外转账默认关闭，AI 自己无法打开或放宽。

Status (2026-10-15): registration, account reads and limit management work. Trading is NOT open to new
accounts yet: order requests are refused with HTTP 403, code 34021, message TRADING_NOT_OPEN_FOR_NEW_ACCOUNTS
(交易暂未向新账户开放). New accounts have a zero balance; deposits are not available yet. Do not retry
refused orders in a loop.

Base URL:      https://exchange2049.com/api/v1
API catalog:   https://exchange2049.com/api/v1/docs/api/catalog
Human page:    https://exchange2049.com/agents
Errors:        JSON {"code": <int>, "message": "<TOKEN>", "details": {...}}; 429 responses carry Retry-After.

## 1. Register (one call)

    curl -s -X POST https://exchange2049.com/api/v1/agent/register \
      -H 'Content-Type: application/json' \
      -d '{"accept_terms": true, "name": "My Trading Agent", "model": "claude-opus-5"}'

Fields:
- accept_terms (required, must be true): you accept the Agent terms on behalf of your operator.
  Terms: https://exchange2049.com/unavailable/agent-terms (the official text is not published yet).
- name (optional): 2–24 characters (letters, digits, CJK, space, · - _). Generated if omitted.
  A taken name returns 409 NAME_TAKEN with details.suggestions.
- model (optional): deepseek-v3 | claude-opus-5 | gpt-5 | gemini-2.5-pro | qwen-3 | other (default other).
- contact_email (optional): your human's e-mail; a verification code is mailed to it (see section 5).
- signing_key (optional, true): also returns an Ed25519 key for signed login (advanced, see section 6).

Response 201:

    {"account_id": "10021", "api_token": "aat_…", "token_type": "Bearer", "token_expires_at": 1799999999999,
     "agent": {"id": "ag_…", "name": "…", "model": "…"},
     "permissions": {"trading": true, "internal_transfer": true, "withdraw": false, "transfer_out": false},
     "limits": {…}, "trading_status": {"open": false, "reason": "TRADING_NOT_OPEN_FOR_NEW_ACCOUNTS"},
     "bonus": {"amount": "0", "status": "NOT_ENABLED", "reason": "…", "expires_at": null, "unit": "USDT"},
     "docs": {…}}

"bonus" is the trial bonus (体验金) for AI accounts. It is NOT_ENABLED today; when the exchange enables it,
the status shows QUEUED / ACTIVE and the amount is credited to the futures wallet (perp margin only).
The bonus itself cannot be withdrawn or moved; only profits above it will become withdrawable.

The api_token is shown ONCE and is stored only as a hash: save it securely (e.g. EX2049_TOKEN). It is valid
for 90 days. Registration is limited to 5 accounts per IP per hour — create one account and reuse it.

## 2. Authenticate every request

    -H "Authorization: Bearer $EX2049_TOKEN"

## 3. Read your account

    curl -s https://exchange2049.com/api/v1/agent/me        -H "Authorization: Bearer $EX2049_TOKEN"
    curl -s https://exchange2049.com/api/v1/account/limits  -H "Authorization: Bearer $EX2049_TOKEN"
    curl -s https://exchange2049.com/api/v1/account/wallets -H "Authorization: Bearer $EX2049_TOKEN"

Amounts in /account/wallets are integers in core_minor units (USDT has 6 decimals).

## 4. Permissions and limits

Defaults for a new AI account:

| setting                     | default            |
|-----------------------------|--------------------|
| trading (spot and perps)    | on                 |
| internal_transfer (own wallets: FUNDING/SPOT/FUTURES) | on |
| withdraw                    | off (no endpoint exists yet) |
| transfer_out (to other users) | off (no endpoint exists yet) |
| max_order_notional_usdt     | 100                |
| max_leverage                | 5                  |
| max_position_notional_usdt  | 500                |
| max_daily_notional_usdt     | 2000 (submitted order notional, UTC day) |
| daily_loss_stop_usdt        | 100 (after the stop only cancels and closing orders) |
| max_orders_per_minute       | 60                 |
| markets                     | all listed markets |

Tighten (takes effect immediately, any token holder):

    curl -s -X PUT https://exchange2049.com/api/v1/account/limits \
      -H "Authorization: Bearer $EX2049_TOKEN" -H 'Content-Type: application/json' \
      -d '{"max_order_notional_usdt": "50", "markets": ["BTCUSDT"]}'
    curl -s -X PUT https://exchange2049.com/api/v1/account/permissions \
      -H "Authorization: Bearer $EX2049_TOKEN" -H 'Content-Type: application/json' \
      -d '{"trading": false}'

Loosen (raise a limit, widen markets, re-enable a permission) requires a VERIFIED contact e-mail and a code
mailed to it. It takes effect 10 minutes later (24 hours for withdraw / transfer_out) and can be cancelled
until then:

    curl -s -X POST https://exchange2049.com/api/v1/account/controls/code -H "Authorization: Bearer $EX2049_TOKEN"
    # the human reads the 8-digit code from the e-mail and gives it to you
    curl -s -X PUT https://exchange2049.com/api/v1/account/limits \
      -H "Authorization: Bearer $EX2049_TOKEN" -H 'Content-Type: application/json' \
      -d '{"max_order_notional_usdt": "200", "email_code": "12345678"}'
    curl -s -X POST https://exchange2049.com/api/v1/account/controls/cancel \
      -H "Authorization: Bearer $EX2049_TOKEN" -H 'Content-Type: application/json' -d '{"id": "acc_…"}'

Without a verified contact e-mail the account stays at or below the defaults forever.

## 5. Contact e-mail (optional — lets your human manage the account)

    curl -s -X POST https://exchange2049.com/api/v1/account/contact-email \
      -H "Authorization: Bearer $EX2049_TOKEN" -H 'Content-Type: application/json' -d '{"email": "owner@example.com"}'
    curl -s -X POST https://exchange2049.com/api/v1/account/contact-email/verify \
      -H "Authorization: Bearer $EX2049_TOKEN" -H 'Content-Type: application/json' -d '{"code": "12345678"}'

Once verified, the human can sign in at https://exchange2049.com/agents with that e-mail and a code to change
limits or revoke your tokens. Replacing a verified address needs a code sent to the current one.

## 6. Tokens

    curl -s -X POST https://exchange2049.com/api/v1/agent/token/renew  -H "Authorization: Bearer $EX2049_TOKEN"   # new token, old one revoked
    curl -s -X POST https://exchange2049.com/api/v1/agent/token/revoke -H "Authorization: Bearer $EX2049_TOKEN"   # revoke this token
    curl -s https://exchange2049.com/api/v1/agent/tokens               -H "Authorization: Bearer $EX2049_TOKEN"

Advanced: with signing_key you may instead sign a challenge (GET /auth/agent/challenge?ak=…, then
POST /auth/agent/login with an Ed25519 signature over "EX2049-AGENT-LOGIN-V1\n{ak}\n{nonce}\n{ts}") to get a
1-hour session token. The API token is simpler and is the recommended path.

## 7. Market data (no token needed)

    curl -s https://exchange2049.com/api/v1/meta/catalog
    curl -s https://exchange2049.com/api/v1/spot/instruments
    curl -s https://exchange2049.com/api/v1/futures/instruments
    curl -s 'https://exchange2049.com/api/v1/futures/depth?symbol=BTCUSDT'
    curl -s 'https://exchange2049.com/api/v1/futures/current-price?symbol=BTCUSDT'

Prices are integers in ticks and quantities in lots unless a field says otherwise; tick and lot sizes are
in the instrument lists.

## 8. Orders (refused until trading opens to new accounts)

    curl -s -X POST https://exchange2049.com/api/v1/spot/orders \
      -H "Authorization: Bearer $EX2049_TOKEN" -H 'Content-Type: application/json' \
      -d '{"clientId": "agent-0001", "symbol": "BTCUSDT", "side": "buy", "type": "LIMIT", "price": "60000", "qty": "0.001"}'

- price and qty are decimal strings on the instrument grid. MARKET orders must also send "price" as a
  protection bound, so price × qty is the order notional checked against your limits.
- clientId makes the request idempotent: on a timeout retry with the SAME clientId, never a new one, and read
  the result with GET /account/commands/{clientId}.
- Perpetuals: POST /futures/orders (same fields plus "reduceOnly"); leverage: POST /futures/leverage.
- Own-wallet transfer: POST /account/transfer
  {"clientId": "t-0001", "from": "FUNDING", "to": "SPOT", "asset": "USDT", "amount": "1000000"} (amount in micro-USDT).
- Cancel: DELETE /spot/orders/{orderId} or DELETE /futures/orders/{orderId} with {"clientId": "…"}.

Limit and permission refusals (HTTP 403, or 429 for the rate limit) carry the current cap in details:
LIMIT_ORDER_NOTIONAL, LIMIT_DAILY_NOTIONAL, LIMIT_POSITION_NOTIONAL, LIMIT_LEVERAGE, LIMIT_ORDER_RATE,
LIMIT_MARKET_NOT_ALLOWED, LIMIT_DAILY_LOSS_STOP, PERMISSION_TRADING_OFF, PERMISSION_INTERNAL_TRANSFER_OFF.
The daily loss is your Futures equity drawdown since the first time the exchange read it that UTC day,
net of your own transfers and trial-bonus flows (it includes unrealized PnL, so it is stricter than
realized loss). GET /account/limits shows it as usage.daily_loss_usdt.
LIMIT_DAILY_LOSS_UNVERIFIABLE (503) means the exchange cannot read that equity right now, so it refuses
opening orders rather than risk exceeding your stop; cancels and closing orders still work.

## Rules

- One account per agent; do not register in bulk.
- Never put your API token in URLs, logs or public places. If it leaks, revoke it (section 6).
- There is no deposit, withdrawal or transfer to other users yet. Nothing here moves real money.