---
title: "Create a new transfer"
method: POST
path: "/entities/{entityDID}/tx"
tags: ["Transfers"]
---

# Create a new transfer

`POST /entities/{entityDID}/tx`

Creates a new transfer from the specified entity to another entity. This is the entry point for initiating a new transfer in the system.

## Path parameters

- `entityDID` string, did, required — Decentralized Identifier (DID)

## Request body

- object
  - `originator` object, required
    - `@id` string, required
  - `beneficiary` object, required
    - `@id` string, required
  - `asset` string, required
  - `amount` string, required
  - `agents` Agent[], required
    - `@id` string, required
    - `role` 'VASP' | 'Custodian' | 'SettlementAddress' | 'SourceAddress' | 'Gateway' | 'Unknown'
    - `for` string
    - `policies` object[]
      - `@type` 'REQUIRE_AUTHORIZATION' | 'REQUIRE_PRESENTATION' | 'REQUIRE_RELATIONSHIP_CONFIRMATION', required
    - `memoTag` string — Optional memo tag or destination tag for address agents (SourceAddress, SettlementAddress)
    - `selectedAsset` string — Asset selected by this agent (CAIP-19 or ISO currency identifier)
    - `selectedSettlementAddress` string — Settlement address selected by this agent
  - `ref` string, required
  - `settlementId` string — Transaction hash in CAIP-220 format (e.g., eip155:1:tx/0x...). Raw hashes are automatically normalized to CAIP-220 when chain context is available from the asset.
  - `transactionValue` object, nullable
    - `amount` string, required
    - `currency` string, required
  - `memoTag` string

## Response `201`

Transfer created successfully

- object
  - `transfer` Transfer, required
    - `@id` string, required
    - `id` string
    - `@type` 'Transfer'
    - `status` 'OUTGOING' | 'INCOMING' | 'AWAITING-YOURS' | 'AWAITING-COUNTERPARTY' | 'REJECTED' | 'AUTHORIZED' | 'FLAGGED' | 'SETTLED' | 'FLAGGED-SETTLEMENT' | 'REVERTED' | 'REVERT-AUTHORIZED' | 'REVERT-REJECTED' | 'REVERT-FLAGGED' | 'FROZEN' | 'CLEARED' | 'REVERT-REQUESTED', required
    - `asset` string, nullable
    - `initiator` string, required
    - `agents` object[], required
      - `@id` string, required
      - `@type` 'TransferAgent'
      - `id` string, nullable
      - `name` string, nullable
      - `agent` object, required
        - `@id` string, required
      - `logo` string, nullable
      - `jurisdiction` string, nullable
      - `did` string, nullable
      - `transferId` string, nullable
      - `role` 'VASP' | 'Custodian' | 'SettlementAddress' | 'SourceAddress' | 'Gateway' | 'Unknown', nullable
      - `for` string, nullable
      - `policies` object[], nullable
        - `@type` string, required
      - `memoTag` string, nullable
      - `status` 'PROCESSING' | 'AUTHORIZED' | 'REJECTED' | 'SETTLED' | 'FAILED' | 'REPLACED' | 'UNREACHABLE', nullable
      - `relationship` object, nullable
        - `@id` string, nullable
        - `from` string, nullable
        - `to` string, nullable
        - `status` string, nullable
        - `confirmedBy` string, nullable
      - `replacement` object, nullable
        - `@id` string, required
    - `createdTime` union
      - string
      - string, date-time
    - `amount` string, nullable
    - `originator` object, nullable
      - `@id` string, required
      - `originatorPerson` object[], nullable
    - `beneficiary` object, nullable
      - `@id` string, required
      - `beneficiaryPerson` object[], nullable
    - `authorizedTime` union
      - string
      - string, date-time
    - `rejectedTime` union
      - string
      - string, date-time
    - `settledTime` union
      - string
      - string, date-time
    - `expiresTime` union
      - string
      - string, date-time
    - `settlementAddress` string, nullable
    - `settlementId` string, nullable
    - `ref` string, nullable
    - `amounts` object[], nullable
      - `id` string, nullable
      - `transferID` string, nullable
      - `entityDID` string, nullable
      - `amount` string, nullable
      - `currency` string, nullable
      - `type` 'PROVIDED' | 'FETCHED_LOCAL_CURRENCY' | 'FETCHED_USD' | 'FETCHED_REGULATORY_COMPLIANCE_CURRENCY', nullable
    - `notabeneAsset` string, nullable
    - `isTravelRule` boolean, nullable
    - `presentationDefinitionUrl` string, nullable
    - `direction` 'OUTGOING' | 'INCOMING', nullable
    - `assetLogo` string, nullable
    - `flags` object[], nullable
    - `authorizationRequested` boolean, nullable
    - `internalAuthorization` 'PENDING' | 'AUTHORIZED' | 'REJECTED', nullable
    - `transactionType` 'TRANSFER' | 'PAYOUT' | 'PAYIN', nullable
    - `revertedTime` union
      - string
      - string, date-time
    - `settlementIdIndex` string, nullable
    - `revertEvidence` string[], nullable
    - `revertMetadata` object, nullable
    - `memoTag` string, nullable
    - `createdAt` union
      - string
      - string, date-time
    - `updatedAt` union
      - string
      - string, date-time
    - `log` object[], nullable
    - `policyEvaluations` object[], nullable
    - `listView` object, nullable
      - `originatorStatus` 'OUTGOING' | 'INCOMING' | 'AWAITING-YOURS' | 'AWAITING-COUNTERPARTY' | 'REJECTED' | 'AUTHORIZED' | 'FLAGGED' | 'SETTLED' | 'FLAGGED-SETTLEMENT' | 'REVERTED' | 'REVERT-AUTHORIZED' | 'REVERT-REJECTED' | 'REVERT-FLAGGED' | 'FROZEN' | 'CLEARED' | 'REVERT-REQUESTED'
      - `beneficiaryStatus` 'OUTGOING' | 'INCOMING' | 'AWAITING-YOURS' | 'AWAITING-COUNTERPARTY' | 'REJECTED' | 'AUTHORIZED' | 'FLAGGED' | 'SETTLED' | 'FLAGGED-SETTLEMENT' | 'REVERTED' | 'REVERT-AUTHORIZED' | 'REVERT-REJECTED' | 'REVERT-FLAGGED' | 'FROZEN' | 'CLEARED' | 'REVERT-REQUESTED'

## Other responses

- `400` — Bad Request - The server could not process the request due to a client error.
- `401` — Unauthorized - Authentication information is missing or invalid.
- `403` — Forbidden - The server understood the request but refuses to authorize it.
- `404` — Not Found - The requested resource could not be found.
- `409` — Conflict - The request could not be completed due to a conflict with the current state of the resource.
- `500` — Internal Server Error - An unexpected condition was encountered on the server.

---

[API](https://skmtc.net/notabene/apis/notabene-api.md) · [All operations](https://skmtc.net/notabene/apis/notabene-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notabene/notabene-api/versions/70056745a433/schema)