Redeems

Burn MYRT from a customer's wallet and pay out MYR. The flow and the reasoning are in the redeem guide; this page states the shapes.

Create a redeem order

POST/v1/redeemsredeem:create

Creates a redeem order for a linked customer and submits it for settlement in the same call, so the key must hold both redeem:create and redeem:execute. A key with only redeem:create receives 403 SCOPE_DENIED. The wallet's on-chain MYRT balance is checked before the order is accepted.

Headers

Header	Required	Value
Authorization	yes	Bearer <key> with redeem:create and redeem:execute
Idempotency-Key	yes	A UUID you generate per logical operation, at most 255 characters
Content-Type	yes	application/json

Request body

Field	Type	Required	Notes
referenceId	string	yes	8 to 100 characters: letters, numbers, dot, underscore, dash, colon. Unique within your integration; reusing one with different details returns 409 IDEMPOTENCY_CONFLICT
amountMyrt	string	yes	Positive decimal, at most 6 decimal places
walletAddress	string	yes	Checksummed EVM address the MYRT is burned from
customerId	string	yes	Owner of the wallet, linked to your integration
bankReference	string	no	Your payout reference, echoed in reconciliation
chainId	number	no	Defaults to the active chain

cURL

curl -X POST https://sandbox-api.myrt.money/v1/redeems \
  -H "Authorization: Bearer $MYRT_API_KEY" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "acme:redeem:2026-09-10:00092",
    "amountMyrt": "500.00",
    "walletAddress": "0xAbC0000000000000000000000000000000000001",
    "customerId": "cus_9f2a3b4c",
    "bankReference": "acme-payout-00092"
  }'

Node.js

import { randomUUID } from "node:crypto";

const res = await fetch("https://sandbox-api.myrt.money/v1/redeems", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MYRT_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    referenceId: "acme:redeem:2026-09-10:00092",
    amountMyrt: "500.00",
    walletAddress: "0xAbC0000000000000000000000000000000000001",
    customerId: "cus_9f2a3b4c",
    bankReference: "acme-payout-00092",
  }),
});
const order = await res.json();

Python

import os, uuid, requests

res = requests.post(
    "https://sandbox-api.myrt.money/v1/redeems",
    headers={
        "Authorization": f"Bearer {os.environ['MYRT_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "referenceId": "acme:redeem:2026-09-10:00092",
        "amountMyrt": "500.00",
        "walletAddress": "0xAbC0000000000000000000000000000000000001",
        "customerId": "cus_9f2a3b4c",
        "bankReference": "acme-payout-00092",
    },
    timeout=30,
)
order = res.json()

Response 201 Created

{
  "ok": true,
  "referenceId": "acme:redeem:2026-09-10:00092",
  "status": "pending",
  "phase": "ORDER_CREATED",
  "direction": "REDEEM",
  "chainId": 1,
  "network": "Ethereum",
  "tokenAddress": "0x...",
  "walletAddress": "0xAbC0000000000000000000000000000000000001",
  "amounts": {
    "myr": "500.00",
    "myrt": "500.00",
    "feeMyr": "0.00",
    "amountRaw": "500000000",
    "decimals": 6
  },
  "blockchain": { "txHash": null, "blockNumber": null },
  "timestamps": { "createdAt": "2026-09-10T04:12:33.918Z", "updatedAt": null }
}

A replay of the same Idempotency-Key and body returns this response again with X-MYRT-Idempotent-Replay: true.

Errors

Code	HTTP
INVALID_JSON	400
IDEMPOTENCY_KEY_REQUIRED	400
INVALID_AMOUNT	400
INVALID_WALLET_ADDRESS	400
INVALID_REFERENCE_ID	400
INSUFFICIENT_BALANCE	400
AMOUNT_NEGATIVE_OR_ZERO	400
AMOUNT_ABOVE_REDEEM_CEILING	400
FOREIGNER_LIMIT_EXCEEDED	400
POLICY_REJECTED	400
MONTHLY_WITHDRAWAL_LIMIT_EXCEEDED	400
SCOPE_DENIED	403
CUSTOMER_NOT_VERIFIED	403
NOT_FOUND	404
IDEMPOTENCY_CONFLICT	409
SETTLEMENT_FAILED	502

INSUFFICIENT_BALANCE carries meta.walletAddress, meta.chainId, meta.requestedMyrt and meta.walletBalanceMyrt. MONTHLY_WITHDRAWAL_LIMIT_EXCEEDED carries meta.monthlyLimit, meta.monthlyCommitted and meta.requestedAmount. See errors for the meaning of each code.

Read a redeem order

GET/v1/redeems/{referenceId}redeem:read

Returns the current state of a redeem order you created. An order created by anyone else, or an order that is not a redeem, returns 404 NOT_FOUND, the same as an order that does not exist.

Path parameters

Parameter	Type	Notes
referenceId	string	The referenceId you supplied on creation

cURL

curl https://sandbox-api.myrt.money/v1/redeems/acme:redeem:2026-09-10:00092 \
  -H "Authorization: Bearer $MYRT_API_KEY"

Node.js

const res = await fetch(
  "https://sandbox-api.myrt.money/v1/redeems/acme:redeem:2026-09-10:00092",
  { headers: { Authorization: `Bearer ${process.env.MYRT_API_KEY}` } }
);
const order = await res.json();

Python

import os, requests

res = requests.get(
    "https://sandbox-api.myrt.money/v1/redeems/acme:redeem:2026-09-10:00092",
    headers={"Authorization": f"Bearer {os.environ['MYRT_API_KEY']}"},
    timeout=30,
)
order = res.json()

Response 200 OK

{
  "ok": true,
  "referenceId": "acme:redeem:2026-09-10:00092",
  "status": "completed",
  "phase": "COMPLETED",
  "direction": "REDEEM",
  "chainId": 1,
  "network": "Ethereum",
  "tokenAddress": "0x...",
  "walletAddress": "0xAbC0000000000000000000000000000000000001",
  "amounts": {
    "myr": "500.00",
    "myrt": "500.00",
    "feeMyr": "0.00",
    "amountRaw": "500000000",
    "decimals": 6
  },
  "blockchain": { "txHash": "0x...", "blockNumber": "20481922" },
  "timestamps": { "createdAt": "2026-09-10T04:12:33.918Z", "updatedAt": "2026-09-10T04:19:02.441Z" }
}

Errors

Code	HTTP
INVALID_REFERENCE_ID	400
NOT_FOUND	404