# Schemas

Data models used by the Direct Trade API.

Product: Direct Trade API
API reference version: 0.1.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/direct-trade-api/0.1.0.yaml
Canonical page: https://docs.axiym.io/direct-trade-api/api-reference/0.1.0/schemas

[Compact reference](/direct-trade-api/api-reference/0.1.0/schemas.md)

## Schema 1: Address

```json
{
  "type": "object",
  "description": "Registered legal address of a business.",
  "required": [
    "address",
    "city",
    "postalCode",
    "country"
  ],
  "properties": {
    "address": {
      "type": "string",
      "description": "First address line.",
      "examples": [
        "10 Anson Road"
      ]
    },
    "addressExtended": {
      "type": "string",
      "description": "Second address line, where applicable.",
      "examples": [
        "#12-01"
      ]
    },
    "city": {
      "type": "string",
      "description": "City or locality.",
      "examples": [
        "Singapore"
      ]
    },
    "district": {
      "type": "string",
      "description": "State, province, or region, where applicable.",
      "examples": [
        "Central Singapore"
      ]
    },
    "postalCode": {
      "type": "string",
      "description": "Postal or ZIP code.",
      "examples": [
        "079903"
      ]
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$",
      "description": "ISO 3166-1 alpha-2 country code.",
      "examples": [
        "SG"
      ]
    }
  }
}
```

## Schema 2: Currency

```json
{
  "type": "string",
  "description": "Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).",
  "examples": [
    "USD"
  ]
}
```

## Schema 3: AccountStatus

```json
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "SUSPENDED",
    "CLOSED"
  ],
  "examples": [
    "ACTIVE"
  ]
}
```

## Schema 4: Account

```json
{
  "type": "object",
  "description": "An account holding a currency balance. Receiving details for funding it are served by the deposit instructions.",
  "required": [
    "accountId",
    "currency",
    "paymentRails",
    "balance",
    "status"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the account settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    },
    "balance": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Current balance.",
      "examples": [
        "48250.00"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/AccountStatus",
      "description": "Account status.",
      "examples": [
        "ACTIVE"
      ]
    }
  }
}
```

## Schema 5: AccountRef

```json
{
  "type": "object",
  "description": "Compact account reference. Fetch the account via `GET /accounts/{accountId}` for the current balance and status; deposit instructions serve its payment details.",
  "required": [
    "accountId",
    "currency",
    "paymentRails"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the account settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  }
}
```

## Schema 6: PaymentRailsCode

```json
{
  "type": "string",
  "description": "Payment rail code the account settles on (e.g. `ZENUS_BANK`, `TRON`).",
  "examples": [
    "ZENUS_BANK"
  ]
}
```

## Schema 7: StatementEntryType

```json
{
  "type": "string",
  "description": "Direction of movement on the account.",
  "enum": [
    "CREDIT",
    "DEBIT"
  ],
  "examples": [
    "DEBIT"
  ]
}
```

## Schema 8: StatementEntry

```json
{
  "type": "object",
  "description": "A posted ledger movement on an account. Entries are returned in posting order and carry the running balance, so consecutive entries reconcile against each other.",
  "required": [
    "entryId",
    "accountId",
    "type",
    "amount",
    "currency",
    "balanceAfter",
    "occurredAt"
  ],
  "properties": {
    "entryId": {
      "type": "string",
      "format": "uuid",
      "description": "Ledger entry identifier (UUID).",
      "examples": [
        "7f9a2d1c-8b31-4f59-9e2f-1d63c4a27b12"
      ]
    },
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a"
      ]
    },
    "type": {
      "$ref": "#/components/schemas/StatementEntryType",
      "description": "Credit or debit direction.",
      "examples": [
        "DEBIT"
      ]
    },
    "amount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Positive movement amount in the account currency; direction is in `type`.",
      "examples": [
        "500.00"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USDT"
      ]
    },
    "balanceBefore": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Running balance before this movement.",
      "examples": [
        "12500.00"
      ]
    },
    "balanceAfter": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Running balance after this movement.",
      "examples": [
        "12000.00"
      ]
    },
    "relatedResourceType": {
      "type": "string",
      "description": "Type of the linked money movement; absent for ledger adjustments with no linked resource.",
      "enum": [
        "DEPOSIT",
        "WITHDRAWAL",
        "CONVERSION",
        "PAYOUT"
      ],
      "examples": [
        "WITHDRAWAL"
      ]
    },
    "relatedResourceId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the linked resource, where present.",
      "examples": [
        "9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e"
      ]
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the movement occurred. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T20:07:31Z"
      ]
    }
  }
}
```

## Schema 9: ConversionStatus

```json
{
  "type": "string",
  "description": "`PENDING` awaits confirmation and appears only in the create response. `ACTIVE` is executing. `COMPLETED` means the funds were exchanged. `CANCELED` means the conversion stopped; see `reasonCode`.\n",
  "enum": [
    "PENDING",
    "ACTIVE",
    "COMPLETED",
    "CANCELED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

## Schema 10: ConversionPair

```json
{
  "type": "object",
  "description": "An allowed exchange direction. You sell the `sell` side and buy the `buy` side. Use its stable `pairId` to create a conversion; Axiym selects the corresponding accounts.",
  "required": [
    "pairId",
    "pair",
    "sell",
    "buy",
    "minAmount"
  ],
  "properties": {
    "pairId": {
      "type": "string",
      "format": "uuid",
      "description": "Conversion pair identifier (UUID), stable for the pair and direction.",
      "examples": [
        "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b"
      ]
    },
    "pair": {
      "type": "string",
      "description": "Pair symbol, `<sellCurrency>-<buyCurrency>`.",
      "examples": [
        "USD-USDT"
      ]
    },
    "sell": {
      "allOf": [
        {
          "$ref": "#/components/schemas/ConversionPairSide"
        }
      ],
      "description": "The side you sell."
    },
    "buy": {
      "allOf": [
        {
          "$ref": "#/components/schemas/ConversionPairSide"
        }
      ],
      "description": "The side you buy."
    },
    "minAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Minimum sell amount, in the sell currency."
    }
  }
}
```

## Schema 11: ConversionPairSide

```json
{
  "type": "object",
  "description": "One side of a conversion pair.",
  "required": [
    "currency",
    "paymentRails"
  ],
  "properties": {
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Side currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the side settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  }
}
```

## Schema 12: ConversionRequest

```json
{
  "type": "object",
  "description": "A conversion along one of your conversion pairs. `pairId` selects the accounts on both sides; `sellAmount` is in the pair's sell currency.\n",
  "required": [
    "pairId",
    "sellAmount"
  ],
  "properties": {
    "pairId": {
      "type": "string",
      "format": "uuid",
      "description": "Conversion pair identifier from `GET /conversion-pairs`.",
      "examples": [
        "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b"
      ]
    },
    "sellAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount to sell. Its currency must be the sell currency of the pair."
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference for correlation, echoed back on related objects.",
      "examples": [
        "conv-2026-0714-01"
      ]
    }
  }
}
```

## Schema 13: Conversion

```json
{
  "type": "object",
  "required": [
    "conversionId",
    "pairId",
    "status",
    "sellAccount",
    "sellAmount",
    "buyAccount",
    "buyAmount",
    "rate",
    "fee",
    "createdAt"
  ],
  "properties": {
    "conversionId": {
      "type": "string",
      "format": "uuid",
      "description": "Conversion identifier (UUID).",
      "examples": [
        "a3f5d7c9-1e2b-4c6a-8d9f-0b1a2c3d4e5f"
      ]
    },
    "pairId": {
      "type": "string",
      "format": "uuid",
      "description": "The conversion pair this conversion runs along.",
      "examples": [
        "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/ConversionStatus",
      "description": "Conversion status.",
      "examples": [
        "COMPLETED"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present when `status` is `CANCELED` — the reason as reported by operations or the liquidity venue. Example: `RATE_EXPIRED`."
    },
    "sellAccount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "The sell-side account, embedded as a compact reference."
    },
    "sellAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount sold, in the sell currency."
    },
    "buyAccount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "The buy-side account, embedded as a compact reference."
    },
    "buyAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount bought and credited to the buy-side account."
    },
    "rate": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Units of buy currency received for one unit of sell currency.",
      "examples": [
        "1.00"
      ]
    },
    "fee": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Fee charged, in the ISO 4217 currency of the pair. It is deducted from the sell amount when buying digital currency and from the buy proceeds when selling it."
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference for correlation, echoed back on related objects.",
      "examples": [
        "conv-2026-0714-01"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T14:00:11Z"
      ]
    },
    "completedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Completion timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T14:05:39Z"
      ]
    }
  }
}
```

## Schema 14: ConversionEventData

```json
{
  "type": "object",
  "description": "A compact notification for routing and correlation. Retrieve the conversion from `GET /conversions/{conversionId}` when you need its amounts, rate, or current state.",
  "required": [
    "conversionId",
    "status"
  ],
  "properties": {
    "conversionId": {
      "type": "string",
      "format": "uuid",
      "description": "Conversion identifier (UUID).",
      "examples": [
        "a3f5d7c9-1e2b-4c6a-8d9f-0b1a2c3d4e5f"
      ]
    },
    "pairId": {
      "type": "string",
      "format": "uuid",
      "description": "The conversion pair this conversion runs along.",
      "examples": [
        "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/ConversionStatus",
      "description": "Conversion status at the time the event was emitted.",
      "examples": [
        "COMPLETED"
      ]
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference submitted on creation, where present.",
      "examples": [
        "conv-2026-0714-01"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present on `conversion.canceled` — the reason as reported by operations or the liquidity venue. Example: `RATE_EXPIRED`."
    }
  }
}
```

## Schema 15: DepositStatus

```json
{
  "type": "string",
  "description": "`PENDING` awaits crediting. `HELD` is temporarily on hold. `COMPLETED` was credited to the account. `CANCELED` or `REJECTED` was not completed; see `reasonCode`.\n",
  "enum": [
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "COMPLETED"
  ]
}
```

## Schema 16: Deposit

```json
{
  "type": "object",
  "required": [
    "depositId",
    "account",
    "amount",
    "status",
    "createdAt"
  ],
  "properties": {
    "depositId": {
      "type": "string",
      "format": "uuid",
      "description": "Deposit identifier (UUID).",
      "examples": [
        "4c8e2b6a-1d9f-4e3b-a7c5-2f0a8d6b4e1c"
      ]
    },
    "account": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "The account the deposit credits, embedded as a compact reference."
    },
    "amount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount credited to the account."
    },
    "fee": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Fee charged, when any."
    },
    "status": {
      "$ref": "#/components/schemas/DepositStatus",
      "description": "Deposit status.",
      "examples": [
        "COMPLETED"
      ]
    },
    "remitterName": {
      "type": "string",
      "description": "Name of the sender, as reported by the sending bank or network.",
      "examples": [
        "Globex Corporation"
      ]
    },
    "code": {
      "type": "string",
      "description": "System-assigned payment code, shown on the payment.",
      "examples": [
        "AXI00000417"
      ]
    },
    "transactionHash": {
      "type": "string",
      "description": "The transaction hash on the network. Present for wallet deposits.",
      "examples": [
        "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present when `status` is `CANCELED` or `REJECTED` — the reason as reported by the bank, the network, or Axiym operations. Example: `SENDER_SCREENING_FAILED`."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-06-14T18:02:11Z"
      ]
    }
  }
}
```

## Schema 17: DepositInstruction

```json
{
  "description": "Axiym's receiving details for the account; the shape matches the account type.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankDepositInstruction"
    },
    {
      "$ref": "#/components/schemas/WalletDepositInstruction"
    }
  ]
}
```

## Schema 18: BankDepositInstruction

```json
{
  "type": "object",
  "title": "Bank transfer",
  "required": [
    "beneficiaryName",
    "accountNumber",
    "swiftBic",
    "bankName"
  ],
  "properties": {
    "beneficiaryName": {
      "type": "string",
      "description": "Name of the receiving party to put on the transfer.",
      "examples": [
        "Axi Labs AG"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Receiving bank account number.",
      "examples": [
        "1050004921"
      ]
    },
    "swiftBic": {
      "type": "string",
      "description": "SWIFT/BIC code of the receiving bank.",
      "examples": [
        "ZEITPRSJXXX"
      ]
    },
    "bankName": {
      "type": "string",
      "description": "Receiving bank name.",
      "examples": [
        "Zenus Bank International Inc."
      ]
    },
    "reference": {
      "type": "string",
      "description": "ISO 11649 creditor reference (`RF` + check digits) assigned by Axiym, formatted in groups of four. Present when the account is funded through a shared receiving account; include it on the transfer so the deposit is matched automatically (matching ignores the spaces). Absent when the receiving account number alone identifies the Axiym account.",
      "examples": [
        "RF11 0004 4901 01"
      ]
    }
  }
}
```

## Schema 19: WalletDepositInstruction

```json
{
  "type": "object",
  "title": "Wallet transfer",
  "required": [
    "walletAddress",
    "network"
  ],
  "properties": {
    "walletAddress": {
      "type": "string",
      "description": "Deposit address of the account; deposits are matched by the address itself.",
      "examples": [
        "TWd2yzw5yFc5W8Tq6CuNZcVJgfmLnBcT4Q"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

## Schema 20: DepositEventData

```json
{
  "type": "object",
  "description": "A compact notification for routing and correlation. Retrieve the deposit from `GET /deposits/{depositId}` when you need its amount, transaction hash, or current state.",
  "required": [
    "depositId",
    "status"
  ],
  "properties": {
    "depositId": {
      "type": "string",
      "format": "uuid",
      "description": "Deposit identifier (UUID).",
      "examples": [
        "4c8e2b6a-1d9f-4e3b-a7c5-2f0a8d6b4e1c"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DepositStatus",
      "description": "Deposit status at the time the event was emitted.",
      "examples": [
        "COMPLETED"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present on `deposit.canceled` / `deposit.rejected` — the reason as reported by the bank, the network, or Axiym operations. Example: `SENDER_SCREENING_FAILED`."
    }
  }
}
```

## Schema 21: DestinationStatus

```json
{
  "type": "string",
  "description": "`PENDING_REVIEW` awaits review. `ACTIVE` may fund deposits and receive withdrawals. `SUSPENDED` is temporarily unavailable. `CLOSED` is permanently retired.\n",
  "enum": [
    "PENDING_REVIEW",
    "ACTIVE",
    "SUSPENDED",
    "CLOSED"
  ],
  "examples": [
    "ACTIVE"
  ]
}
```

## Schema 22: AddressBookEntry

```json
{
  "description": "An address book entry — a registered external bank account or wallet you own. The variant is signaled by its fields: a bank destination carries `accountNumber` and the `bank` block; a wallet destination carries `walletAddress` and `network`. The two sets never appear together.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankAddressBookEntry"
    },
    {
      "$ref": "#/components/schemas/WalletAddressBookEntry"
    }
  ]
}
```

## Schema 23: BankAddressBookEntry

```json
{
  "type": "object",
  "title": "Bank account",
  "required": [
    "destinationId",
    "status",
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry identifier (UUID).",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Address book entry status.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the address book entry.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-06-12T14:05:00Z"
      ]
    }
  }
}
```

## Schema 24: WalletAddressBookEntry

```json
{
  "type": "object",
  "title": "Wallet address",
  "required": [
    "destinationId",
    "status",
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry identifier (UUID).",
      "examples": [
        "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Address book entry status.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the address book entry.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address of the entry; static and reusable.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-06-12T14:05:00Z"
      ]
    }
  }
}
```

## Schema 25: Destination

```json
{
  "description": "Where the funds are delivered, as recorded on the operation at creation time. This is a snapshot: it carries the account or wallet details and, when the destination was taken from the address book, its `destinationId`. It does not carry the address book entry's status or creation date; read the address book entry for its current state.\n\n- A bank destination contains `accountNumber` and `bank`.\n- A wallet destination contains `walletAddress` and `network`.\n\nThe two field sets never appear together.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankDestination"
    },
    {
      "$ref": "#/components/schemas/WalletDestination"
    }
  ]
}
```

## Schema 26: BankDestination

```json
{
  "type": "object",
  "title": "Bank account",
  "required": [
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number or IBAN.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    }
  }
}
```

## Schema 27: WalletDestination

```json
{
  "type": "object",
  "title": "Wallet address",
  "required": [
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address on the given network.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

## Schema 28: Bank

```json
{
  "type": "object",
  "description": "Destination bank details. Present on bank destinations only. The address country selects the applicable corridor rules.",
  "additionalProperties": false,
  "required": [
    "bankName",
    "address"
  ],
  "properties": {
    "bankName": {
      "type": "string",
      "minLength": 1,
      "description": "Bank name.",
      "examples": [
        "Bank of America"
      ]
    },
    "address": {
      "$ref": "#/components/schemas/BankAddress"
    },
    "swiftBic": {
      "type": "string",
      "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
      "description": "ISO 9362 SWIFT/BIC, when required for the corridor.",
      "examples": [
        "BOFAUS3NXXX"
      ]
    },
    "clearingCode": {
      "type": "string",
      "description": "Local clearing or routing code, when required for the corridor.",
      "examples": [
        "026009593"
      ]
    },
    "clearingSystemCode": {
      "type": "string",
      "description": "Clearing system the code belongs to. Axiym derives it from the bank country; supply it where a country has more than one system.",
      "examples": [
        "USABA"
      ]
    }
  }
}
```

## Schema 29: BankAddress

```json
{
  "type": "object",
  "description": "Postal address of the bank. Only the country is required — it selects the corridor rules. Supply the rest when the corridor or a correspondent asks for it.",
  "additionalProperties": false,
  "required": [
    "country"
  ],
  "properties": {
    "streetName": {
      "type": "string"
    },
    "buildingNumber": {
      "type": "string"
    },
    "city": {
      "type": "string",
      "examples": [
        "New York"
      ]
    },
    "region": {
      "type": "string"
    },
    "postalCode": {
      "type": "string"
    },
    "country": {
      "$ref": "#/components/schemas/CountryCode"
    }
  }
}
```

## Schema 30: CountryCode

```json
{
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "description": "ISO 3166-1 alpha-2 country code.",
  "examples": [
    "US"
  ]
}
```

## Schema 31: BankDestinationRequest

```json
{
  "type": "object",
  "description": "Add an owned external bank account to the address book as a permitted deposit source and withdrawal recipient. The entry starts in `PENDING_REVIEW`.",
  "required": [
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the external bank account.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    }
  }
}
```

## Schema 32: WalletDestinationRequest

```json
{
  "type": "object",
  "description": "Add an owned external wallet to the address book as a permitted deposit source and withdrawal recipient. The entry starts in `PENDING_REVIEW`.",
  "required": [
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the external wallet.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address to register as an external account.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

## Schema 33: PageInfo

```json
{
  "type": "object",
  "properties": {
    "hasNextPage": {
      "type": "boolean",
      "description": "When paginating forwards, are there more items?",
      "examples": [
        true
      ]
    },
    "endCursor": {
      "type": "string",
      "description": "When paginating forwards, the cursor to continue.",
      "examples": [
        "eyJvZmZzZXQiOjI1fQ=="
      ]
    }
  },
  "required": [
    "hasNextPage"
  ]
}
```

## Schema 34: WithdrawalStatus

```json
{
  "type": "string",
  "description": "`PENDING_CONFIRMATION` is awaiting explicit confirmation and has not started execution. `PENDING` is queued for execution. `HELD` is temporarily on hold — no action needed from you. `COMPLETED` is done. `CANCELED` and `REJECTED` did not complete (see `reasonCode`).\n",
  "enum": [
    "PENDING_CONFIRMATION",
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

## Schema 35: Withdrawal

```json
{
  "type": "object",
  "required": [
    "withdrawalId",
    "sourceAccount",
    "sourceAmount",
    "destinationAmount",
    "fee",
    "destination",
    "status",
    "createdAt"
  ],
  "properties": {
    "withdrawalId": {
      "type": "string",
      "format": "uuid",
      "description": "Withdrawal identifier (UUID).",
      "examples": [
        "9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e"
      ]
    },
    "sourceAccount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "The source account, embedded as a compact reference."
    },
    "sourceAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount debited from the source account, in the source account currency."
    },
    "destinationAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount delivered to the destination, in the destination currency. Equals `sourceAmount` less `fee`."
    },
    "fee": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Total deducted from `sourceAmount` before delivery, in the source account currency. Zero when no fee applies."
    },
    "destination": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Destination"
        }
      ],
      "description": "Snapshot of the destination selected by `destinationId` at creation time."
    },
    "status": {
      "$ref": "#/components/schemas/WithdrawalStatus",
      "description": "Withdrawal status.",
      "examples": [
        "COMPLETED"
      ]
    },
    "code": {
      "type": "string",
      "description": "System-assigned payment code, shown on the payment.",
      "examples": [
        "AXI00000418"
      ]
    },
    "reference": {
      "type": "string",
      "description": "Text shown to the recipient, as submitted.",
      "examples": [
        "Treasury sweep"
      ]
    },
    "supportingDocuments": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SupportingDocument"
      },
      "description": "Documents accepted with the payment. File content is not returned."
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference for correlation, echoed back on related objects.",
      "examples": [
        "wd-2026-0714-01"
      ]
    },
    "transactionHash": {
      "type": "string",
      "description": "The transaction hash on the network. Present for wallet withdrawals once the withdrawal is `COMPLETED`.",
      "examples": [
        "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present when `status` is `CANCELED` or `REJECTED` — the cancellation/rejection reason as reported by the bank, the network, or Axiym operations. Example: `INSUFFICIENT_BENEFICIARY_DETAILS`."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T20:06:50Z"
      ]
    }
  }
}
```

## Schema 36: WithdrawalRequest

```json
{
  "type": "object",
  "description": "A withdrawal from `sourceAccountId` to an address book entry. `sourceAmount` is debited from the source account in its currency. The `destinationId` must be `ACTIVE` and use the same currency. Creating the withdrawal returns `PENDING_CONFIRMATION`; call `POST /withdrawals/{withdrawalId}/confirm` to begin execution.\n",
  "additionalProperties": false,
  "required": [
    "sourceAccountId",
    "sourceAmount",
    "destinationId"
  ],
  "properties": {
    "sourceAccountId": {
      "type": "string",
      "format": "uuid",
      "description": "Source account identifier (UUID).",
      "examples": [
        "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a"
      ]
    },
    "sourceAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount to debit from the source account. Its currency must be the source account currency."
    },
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the address book entry to pay. It must be `ACTIVE` and in the source Axiym account's currency.",
      "examples": [
        "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c"
      ]
    },
    "reference": {
      "type": "string",
      "maxLength": 140,
      "description": "Text shown to the recipient, typically the invoice number.",
      "examples": [
        "Invoice INV-20416"
      ]
    },
    "supportingDocuments": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "$ref": "#/components/schemas/SupportingDocumentInput"
      },
      "description": "Documents supporting the payment, such as an invoice. Required where the destination corridor requires evidence."
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference for correlation, echoed back on related objects.",
      "examples": [
        "wd-2026-0714-01"
      ]
    }
  }
}
```

## Schema 37: SupportingDocumentType

```json
{
  "type": "string",
  "description": "Axiym classification of evidence supplied with a payout.",
  "enum": [
    "PASSPORT",
    "NATIONAL_ID",
    "DRIVER_LICENSE",
    "RESIDENCE_PERMIT",
    "PROOF_OF_ADDRESS",
    "UTILITY_BILL",
    "BANK_STATEMENT",
    "TAX_CERTIFICATE",
    "CERTIFICATE_OF_INCORPORATION",
    "REGISTRY_EXTRACT",
    "ARTICLES_OF_ASSOCIATION",
    "SHAREHOLDER_REGISTER",
    "DIRECTOR_REGISTER",
    "UBO_DECLARATION",
    "POWER_OF_ATTORNEY",
    "BOARD_RESOLUTION",
    "REGULATORY_LICENSE",
    "BUSINESS_LICENSE",
    "FINANCIAL_STATEMENT",
    "AUDIT_REPORT",
    "SOURCE_OF_FUNDS",
    "INVOICE",
    "CONTRACT",
    "PURCHASE_ORDER",
    "PAYROLL_FILE",
    "LOAN_AGREEMENT",
    "SHIPPING_DOCUMENT",
    "CUSTOMS_DECLARATION",
    "OTHER"
  ],
  "examples": [
    "INVOICE"
  ]
}
```

## Schema 38: SupportingDocumentInput

```json
{
  "type": "object",
  "description": "A document supporting the payment, such as an invoice or contract. One item is one file of up to 10 MB in PDF, JPEG or PNG format; supply the file content as base64.",
  "additionalProperties": false,
  "required": [
    "documentType",
    "data",
    "name"
  ],
  "properties": {
    "documentType": {
      "$ref": "#/components/schemas/SupportingDocumentType"
    },
    "data": {
      "type": "string",
      "contentEncoding": "base64",
      "description": "Complete file encoded as base64 from its raw bytes. Do not include a data-URL prefix."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "File name, including the extension.",
      "examples": [
        "INV-20416.pdf"
      ]
    }
  }
}
```

## Schema 39: SupportingDocument

```json
{
  "type": "object",
  "description": "Metadata of a document accepted with the payment. File content is not returned.",
  "additionalProperties": false,
  "required": [
    "documentType",
    "fileId",
    "name",
    "contentType",
    "size"
  ],
  "properties": {
    "documentType": {
      "$ref": "#/components/schemas/SupportingDocumentType"
    },
    "fileId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the stored file."
    },
    "name": {
      "type": "string",
      "description": "File name supplied with the document."
    },
    "contentType": {
      "type": "string",
      "description": "MIME type detected from the file content.",
      "examples": [
        "application/pdf"
      ]
    },
    "size": {
      "type": "integer",
      "description": "File size in bytes."
    }
  }
}
```

## Schema 40: WithdrawalEventData

```json
{
  "type": "object",
  "description": "A compact notification for routing and correlation. Retrieve the withdrawal from `GET /withdrawals/{withdrawalId}` when you need its amount, fees, transaction hash, or current state.",
  "required": [
    "withdrawalId",
    "status"
  ],
  "properties": {
    "withdrawalId": {
      "type": "string",
      "format": "uuid",
      "description": "Withdrawal identifier (UUID).",
      "examples": [
        "9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/WithdrawalStatus",
      "description": "Withdrawal status at the time the event was emitted.",
      "examples": [
        "COMPLETED"
      ]
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference submitted on creation, where present.",
      "examples": [
        "wd-2026-0714-01"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present on `withdrawal.canceled` / `withdrawal.rejected` — the reason as reported by the bank, the network, or Axiym operations. Example: `INSUFFICIENT_BENEFICIARY_DETAILS`."
    }
  }
}
```

## Schema 41: AccountMovementEventData

```json
{
  "type": "object",
  "description": "A posted account movement. The event includes the movement amount but not the current balance. Retrieve the account when you need its latest balance.",
  "required": [
    "accountId",
    "amount",
    "currency",
    "occurredAt"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a"
      ]
    },
    "amount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Decimal"
        }
      ],
      "description": "Positive movement amount in the account currency; direction is in the event type.",
      "examples": [
        "500.00"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USDT"
      ]
    },
    "relatedResourceType": {
      "type": "string",
      "description": "Type of the linked money movement; absent for movements with no linked API resource.",
      "enum": [
        "DEPOSIT",
        "WITHDRAWAL",
        "CONVERSION",
        "PAYOUT"
      ],
      "examples": [
        "WITHDRAWAL"
      ]
    },
    "relatedResourceId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the linked resource, where present.",
      "examples": [
        "9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e"
      ]
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the movement occurred. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T20:07:31Z"
      ]
    }
  }
}
```

## Schema 42: AccountStatusEventData

```json
{
  "type": "object",
  "description": "Account lifecycle notification.",
  "required": [
    "accountId",
    "status"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/AccountStatus",
      "description": "Account status at the time the event was emitted.",
      "examples": [
        "SUSPENDED"
      ]
    }
  }
}
```

## Schema 43: DestinationEventData

```json
{
  "type": "object",
  "description": "Address book entry lifecycle notification. The contract retains the `destinationId` field name and the `destination.*` event names.",
  "required": [
    "destinationId",
    "status"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry identifier (UUID).",
      "examples": [
        "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Address book entry status when the event was emitted.",
      "examples": [
        "ACTIVE"
      ]
    }
  }
}
```

## Schema 44: Event

```json
{
  "type": "object",
  "description": "Webhook event envelope delivered to your registered endpoint.",
  "required": [
    "id",
    "timestamp",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Event ID. Use this for de-duplication.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "Event timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T20:08:00Z"
      ]
    },
    "type": {
      "type": "string",
      "description": "Event type.",
      "examples": [
        "withdrawal.completed"
      ]
    },
    "data": {
      "type": "object",
      "properties": {},
      "description": "Event data."
    }
  }
}
```

## Schema 45: Subscription

```json
{
  "type": "object",
  "properties": {
    "subscriptionId": {
      "type": "string",
      "description": "Subscription identifier (UUID).",
      "format": "uuid",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "endpoint": {
      "type": "string",
      "description": "URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request.",
      "title": "",
      "format": "uri",
      "examples": [
        "https://api.acme.example/webhooks"
      ]
    }
  },
  "required": [
    "subscriptionId",
    "endpoint"
  ]
}
```

## Schema 46: RequestStatus

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Request status.",
      "examples": [
        "OK"
      ],
      "default": "OK",
      "enum": [
        "OK"
      ]
    }
  },
  "required": [
    "status"
  ]
}
```

## Schema 47: PublicKey

```json
{
  "type": "object",
  "properties": {
    "publicKeyId": {
      "type": "string",
      "description": "Public key identifier (UUID).",
      "format": "uuid",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "active": {
      "type": "boolean",
      "description": "Indicates whether the key is active",
      "examples": [
        true
      ]
    },
    "algorithm": {
      "type": "string",
      "description": "Encryption algorithm",
      "examples": [
        "ED25519"
      ]
    },
    "publicKey": {
      "type": "string",
      "description": "Public Key",
      "examples": [
        "string"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T20:08:00Z"
      ]
    }
  },
  "required": [
    "publicKeyId",
    "algorithm",
    "publicKey",
    "createdAt",
    "active"
  ]
}
```

## Schema 48: Money

```json
{
  "type": "object",
  "description": "Monetary amount and its currency.",
  "additionalProperties": false,
  "required": [
    "amount",
    "currency"
  ],
  "properties": {
    "amount": {
      "$ref": "#/components/schemas/Decimal"
    },
    "currency": {
      "$ref": "#/components/schemas/Currency"
    }
  }
}
```

## Schema 49: Decimal

```json
{
  "type": "string",
  "description": "Decimal number serialized as a string to preserve precision. Amounts sent to Axiym are positive and carry at most 8 decimal places.",
  "examples": [
    "1000.00"
  ]
}
```

## Schema 50: ExternalReference

```json
{
  "type": "string",
  "maxLength": 255,
  "description": "Your optional identifier for correlating the resource with your system. Axiym returns it on reads. It does not make retries safe; use `Idempotency-Key` for that.\n",
  "examples": [
    "wd-2026-0714-01"
  ]
}
```

## Schema 51: ValidationFieldErrors

```json
{
  "description": "Nested validation errors keyed by field name or array index. Leaf values are arrays of `ValidationError` objects.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      }
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ValidationFieldErrors"
      },
      "properties": {}
    }
  ]
}
```

## Schema 52: Network

```json
{
  "type": "string",
  "description": "Wallet network.",
  "enum": [
    "TRON",
    "AVALANCHE"
  ],
  "examples": [
    "TRON"
  ]
}
```

## Schema 53: ValidationError

```json
{
  "type": "object",
  "description": "One field-level validation error.",
  "properties": {
    "code": {
      "type": "string",
      "description": "Validation rule code (e.g. 'length', 'email', 'invalid_currency', 'disbursement_account_required').",
      "examples": [
        "length"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable message.",
      "examples": [
        "string"
      ]
    },
    "params": {
      "type": "object",
      "description": "Rule-specific parameters. Always includes `value` (the offending input). Additional keys depend on the rule (e.g. `min`, `max` for length).",
      "properties": {
        "value": {
          "description": "The submitted value that failed validation.",
          "examples": [
            "string"
          ]
        }
      }
    }
  },
  "required": [
    "code",
    "params"
  ]
}
```

## Referenced definitions

- [`#/components/schemas/Currency`](#definition-1)
- [`#/components/schemas/PaymentRailsCode`](#definition-2)
- [`#/components/schemas/Decimal`](#definition-3)
- [`#/components/schemas/AccountStatus`](#definition-4)
- [`#/components/schemas/StatementEntryType`](#definition-5)
- [`#/components/schemas/ConversionPairSide`](#definition-6)
- [`#/components/schemas/Money`](#definition-7)
- [`#/components/schemas/ExternalReference`](#definition-8)
- [`#/components/schemas/ConversionStatus`](#definition-9)
- [`#/components/schemas/AccountRef`](#definition-10)
- [`#/components/schemas/DepositStatus`](#definition-11)
- [`#/components/schemas/BankDepositInstruction`](#definition-12)
- [`#/components/schemas/WalletDepositInstruction`](#definition-13)
- [`#/components/schemas/Network`](#definition-14)
- [`#/components/schemas/BankAddressBookEntry`](#definition-15)
- [`#/components/schemas/DestinationStatus`](#definition-16)
- [`#/components/schemas/Bank`](#definition-17)
- [`#/components/schemas/BankAddress`](#definition-18)
- [`#/components/schemas/CountryCode`](#definition-19)
- [`#/components/schemas/WalletAddressBookEntry`](#definition-20)
- [`#/components/schemas/BankDestination`](#definition-21)
- [`#/components/schemas/WalletDestination`](#definition-22)
- [`#/components/schemas/Destination`](#definition-23)
- [`#/components/schemas/WithdrawalStatus`](#definition-24)
- [`#/components/schemas/SupportingDocument`](#definition-25)
- [`#/components/schemas/SupportingDocumentType`](#definition-26)
- [`#/components/schemas/SupportingDocumentInput`](#definition-27)
- [`#/components/schemas/ValidationError`](#definition-28)
- [`#/components/schemas/ValidationFieldErrors`](#definition-29)

### definition-1

`#/components/schemas/Currency`

```json
{
  "type": "string",
  "description": "Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).",
  "examples": [
    "USD"
  ]
}
```

### definition-2

`#/components/schemas/PaymentRailsCode`

```json
{
  "type": "string",
  "description": "Payment rail code the account settles on (e.g. `ZENUS_BANK`, `TRON`).",
  "examples": [
    "ZENUS_BANK"
  ]
}
```

### definition-3

`#/components/schemas/Decimal`

```json
{
  "type": "string",
  "description": "Decimal number serialized as a string to preserve precision. Amounts sent to Axiym are positive and carry at most 8 decimal places.",
  "examples": [
    "1000.00"
  ]
}
```

### definition-4

`#/components/schemas/AccountStatus`

```json
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "SUSPENDED",
    "CLOSED"
  ],
  "examples": [
    "ACTIVE"
  ]
}
```

### definition-5

`#/components/schemas/StatementEntryType`

```json
{
  "type": "string",
  "description": "Direction of movement on the account.",
  "enum": [
    "CREDIT",
    "DEBIT"
  ],
  "examples": [
    "DEBIT"
  ]
}
```

### definition-6

`#/components/schemas/ConversionPairSide`

```json
{
  "type": "object",
  "description": "One side of a conversion pair.",
  "required": [
    "currency",
    "paymentRails"
  ],
  "properties": {
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Side currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the side settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  }
}
```

### definition-7

`#/components/schemas/Money`

```json
{
  "type": "object",
  "description": "Monetary amount and its currency.",
  "additionalProperties": false,
  "required": [
    "amount",
    "currency"
  ],
  "properties": {
    "amount": {
      "$ref": "#/components/schemas/Decimal"
    },
    "currency": {
      "$ref": "#/components/schemas/Currency"
    }
  }
}
```

### definition-8

`#/components/schemas/ExternalReference`

```json
{
  "type": "string",
  "maxLength": 255,
  "description": "Your optional identifier for correlating the resource with your system. Axiym returns it on reads. It does not make retries safe; use `Idempotency-Key` for that.\n",
  "examples": [
    "wd-2026-0714-01"
  ]
}
```

### definition-9

`#/components/schemas/ConversionStatus`

```json
{
  "type": "string",
  "description": "`PENDING` awaits confirmation and appears only in the create response. `ACTIVE` is executing. `COMPLETED` means the funds were exchanged. `CANCELED` means the conversion stopped; see `reasonCode`.\n",
  "enum": [
    "PENDING",
    "ACTIVE",
    "COMPLETED",
    "CANCELED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

### definition-10

`#/components/schemas/AccountRef`

```json
{
  "type": "object",
  "description": "Compact account reference. Fetch the account via `GET /accounts/{accountId}` for the current balance and status; deposit instructions serve its payment details.",
  "required": [
    "accountId",
    "currency",
    "paymentRails"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the account settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  }
}
```

### definition-11

`#/components/schemas/DepositStatus`

```json
{
  "type": "string",
  "description": "`PENDING` awaits crediting. `HELD` is temporarily on hold. `COMPLETED` was credited to the account. `CANCELED` or `REJECTED` was not completed; see `reasonCode`.\n",
  "enum": [
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "COMPLETED"
  ]
}
```

### definition-12

`#/components/schemas/BankDepositInstruction`

```json
{
  "type": "object",
  "title": "Bank transfer",
  "required": [
    "beneficiaryName",
    "accountNumber",
    "swiftBic",
    "bankName"
  ],
  "properties": {
    "beneficiaryName": {
      "type": "string",
      "description": "Name of the receiving party to put on the transfer.",
      "examples": [
        "Axi Labs AG"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Receiving bank account number.",
      "examples": [
        "1050004921"
      ]
    },
    "swiftBic": {
      "type": "string",
      "description": "SWIFT/BIC code of the receiving bank.",
      "examples": [
        "ZEITPRSJXXX"
      ]
    },
    "bankName": {
      "type": "string",
      "description": "Receiving bank name.",
      "examples": [
        "Zenus Bank International Inc."
      ]
    },
    "reference": {
      "type": "string",
      "description": "ISO 11649 creditor reference (`RF` + check digits) assigned by Axiym, formatted in groups of four. Present when the account is funded through a shared receiving account; include it on the transfer so the deposit is matched automatically (matching ignores the spaces). Absent when the receiving account number alone identifies the Axiym account.",
      "examples": [
        "RF11 0004 4901 01"
      ]
    }
  }
}
```

### definition-13

`#/components/schemas/WalletDepositInstruction`

```json
{
  "type": "object",
  "title": "Wallet transfer",
  "required": [
    "walletAddress",
    "network"
  ],
  "properties": {
    "walletAddress": {
      "type": "string",
      "description": "Deposit address of the account; deposits are matched by the address itself.",
      "examples": [
        "TWd2yzw5yFc5W8Tq6CuNZcVJgfmLnBcT4Q"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

### definition-14

`#/components/schemas/Network`

```json
{
  "type": "string",
  "description": "Wallet network.",
  "enum": [
    "TRON",
    "AVALANCHE"
  ],
  "examples": [
    "TRON"
  ]
}
```

### definition-15

`#/components/schemas/BankAddressBookEntry`

```json
{
  "type": "object",
  "title": "Bank account",
  "required": [
    "destinationId",
    "status",
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry identifier (UUID).",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Address book entry status.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the address book entry.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-06-12T14:05:00Z"
      ]
    }
  }
}
```

### definition-16

`#/components/schemas/DestinationStatus`

```json
{
  "type": "string",
  "description": "`PENDING_REVIEW` awaits review. `ACTIVE` may fund deposits and receive withdrawals. `SUSPENDED` is temporarily unavailable. `CLOSED` is permanently retired.\n",
  "enum": [
    "PENDING_REVIEW",
    "ACTIVE",
    "SUSPENDED",
    "CLOSED"
  ],
  "examples": [
    "ACTIVE"
  ]
}
```

### definition-17

`#/components/schemas/Bank`

```json
{
  "type": "object",
  "description": "Destination bank details. Present on bank destinations only. The address country selects the applicable corridor rules.",
  "additionalProperties": false,
  "required": [
    "bankName",
    "address"
  ],
  "properties": {
    "bankName": {
      "type": "string",
      "minLength": 1,
      "description": "Bank name.",
      "examples": [
        "Bank of America"
      ]
    },
    "address": {
      "$ref": "#/components/schemas/BankAddress"
    },
    "swiftBic": {
      "type": "string",
      "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
      "description": "ISO 9362 SWIFT/BIC, when required for the corridor.",
      "examples": [
        "BOFAUS3NXXX"
      ]
    },
    "clearingCode": {
      "type": "string",
      "description": "Local clearing or routing code, when required for the corridor.",
      "examples": [
        "026009593"
      ]
    },
    "clearingSystemCode": {
      "type": "string",
      "description": "Clearing system the code belongs to. Axiym derives it from the bank country; supply it where a country has more than one system.",
      "examples": [
        "USABA"
      ]
    }
  }
}
```

### definition-18

`#/components/schemas/BankAddress`

```json
{
  "type": "object",
  "description": "Postal address of the bank. Only the country is required — it selects the corridor rules. Supply the rest when the corridor or a correspondent asks for it.",
  "additionalProperties": false,
  "required": [
    "country"
  ],
  "properties": {
    "streetName": {
      "type": "string"
    },
    "buildingNumber": {
      "type": "string"
    },
    "city": {
      "type": "string",
      "examples": [
        "New York"
      ]
    },
    "region": {
      "type": "string"
    },
    "postalCode": {
      "type": "string"
    },
    "country": {
      "$ref": "#/components/schemas/CountryCode"
    }
  }
}
```

### definition-19

`#/components/schemas/CountryCode`

```json
{
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "description": "ISO 3166-1 alpha-2 country code.",
  "examples": [
    "US"
  ]
}
```

### definition-20

`#/components/schemas/WalletAddressBookEntry`

```json
{
  "type": "object",
  "title": "Wallet address",
  "required": [
    "destinationId",
    "status",
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry identifier (UUID).",
      "examples": [
        "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c"
      ]
    },
    "status": {
      "$ref": "#/components/schemas/DestinationStatus",
      "description": "Address book entry status.",
      "examples": [
        "ACTIVE"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency associated with the address book entry.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address of the entry; static and reusable.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-06-12T14:05:00Z"
      ]
    }
  }
}
```

### definition-21

`#/components/schemas/BankDestination`

```json
{
  "type": "object",
  "title": "Bank account",
  "required": [
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number or IBAN.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    }
  }
}
```

### definition-22

`#/components/schemas/WalletDestination`

```json
{
  "type": "object",
  "title": "Wallet address",
  "required": [
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address on the given network.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

### definition-23

`#/components/schemas/Destination`

```json
{
  "description": "Where the funds are delivered, as recorded on the operation at creation time. This is a snapshot: it carries the account or wallet details and, when the destination was taken from the address book, its `destinationId`. It does not carry the address book entry's status or creation date; read the address book entry for its current state.\n\n- A bank destination contains `accountNumber` and `bank`.\n- A wallet destination contains `walletAddress` and `network`.\n\nThe two field sets never appear together.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankDestination"
    },
    {
      "$ref": "#/components/schemas/WalletDestination"
    }
  ]
}
```

### definition-24

`#/components/schemas/WithdrawalStatus`

```json
{
  "type": "string",
  "description": "`PENDING_CONFIRMATION` is awaiting explicit confirmation and has not started execution. `PENDING` is queued for execution. `HELD` is temporarily on hold — no action needed from you. `COMPLETED` is done. `CANCELED` and `REJECTED` did not complete (see `reasonCode`).\n",
  "enum": [
    "PENDING_CONFIRMATION",
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

### definition-25

`#/components/schemas/SupportingDocument`

```json
{
  "type": "object",
  "description": "Metadata of a document accepted with the payment. File content is not returned.",
  "additionalProperties": false,
  "required": [
    "documentType",
    "fileId",
    "name",
    "contentType",
    "size"
  ],
  "properties": {
    "documentType": {
      "$ref": "#/components/schemas/SupportingDocumentType"
    },
    "fileId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the stored file."
    },
    "name": {
      "type": "string",
      "description": "File name supplied with the document."
    },
    "contentType": {
      "type": "string",
      "description": "MIME type detected from the file content.",
      "examples": [
        "application/pdf"
      ]
    },
    "size": {
      "type": "integer",
      "description": "File size in bytes."
    }
  }
}
```

### definition-26

`#/components/schemas/SupportingDocumentType`

```json
{
  "type": "string",
  "description": "Axiym classification of evidence supplied with a payout.",
  "enum": [
    "PASSPORT",
    "NATIONAL_ID",
    "DRIVER_LICENSE",
    "RESIDENCE_PERMIT",
    "PROOF_OF_ADDRESS",
    "UTILITY_BILL",
    "BANK_STATEMENT",
    "TAX_CERTIFICATE",
    "CERTIFICATE_OF_INCORPORATION",
    "REGISTRY_EXTRACT",
    "ARTICLES_OF_ASSOCIATION",
    "SHAREHOLDER_REGISTER",
    "DIRECTOR_REGISTER",
    "UBO_DECLARATION",
    "POWER_OF_ATTORNEY",
    "BOARD_RESOLUTION",
    "REGULATORY_LICENSE",
    "BUSINESS_LICENSE",
    "FINANCIAL_STATEMENT",
    "AUDIT_REPORT",
    "SOURCE_OF_FUNDS",
    "INVOICE",
    "CONTRACT",
    "PURCHASE_ORDER",
    "PAYROLL_FILE",
    "LOAN_AGREEMENT",
    "SHIPPING_DOCUMENT",
    "CUSTOMS_DECLARATION",
    "OTHER"
  ],
  "examples": [
    "INVOICE"
  ]
}
```

### definition-27

`#/components/schemas/SupportingDocumentInput`

```json
{
  "type": "object",
  "description": "A document supporting the payment, such as an invoice or contract. One item is one file of up to 10 MB in PDF, JPEG or PNG format; supply the file content as base64.",
  "additionalProperties": false,
  "required": [
    "documentType",
    "data",
    "name"
  ],
  "properties": {
    "documentType": {
      "$ref": "#/components/schemas/SupportingDocumentType"
    },
    "data": {
      "type": "string",
      "contentEncoding": "base64",
      "description": "Complete file encoded as base64 from its raw bytes. Do not include a data-URL prefix."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "File name, including the extension.",
      "examples": [
        "INV-20416.pdf"
      ]
    }
  }
}
```

### definition-28

`#/components/schemas/ValidationError`

```json
{
  "type": "object",
  "description": "One field-level validation error.",
  "properties": {
    "code": {
      "type": "string",
      "description": "Validation rule code (e.g. 'length', 'email', 'invalid_currency', 'disbursement_account_required').",
      "examples": [
        "length"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable message.",
      "examples": [
        "string"
      ]
    },
    "params": {
      "type": "object",
      "description": "Rule-specific parameters. Always includes `value` (the offending input). Additional keys depend on the rule (e.g. `min`, `max` for length).",
      "properties": {
        "value": {
          "description": "The submitted value that failed validation.",
          "examples": [
            "string"
          ]
        }
      }
    }
  },
  "required": [
    "code",
    "params"
  ]
}
```

### definition-29

`#/components/schemas/ValidationFieldErrors`

```json
{
  "description": "Nested validation errors keyed by field name or array index. Leaf values are arrays of `ValidationError` objects.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      }
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ValidationFieldErrors"
      },
      "properties": {}
    }
  ]
}
```