Reference · Transfers

Create a transfer

Initiate a movement of value from a source holding to a destination.

POST/v1/transfers

Authorization: Bearer ak_test_… · Application API key

Idempotency-Key: <uuid> · required

semantic: transfer_initiation_command

Key capabilities

TransferCreate

Conditional, gating specific request features; a request that uses one without it is refused:

TransferAppFeeInstructionRequest
TransferApplicationPaysAppFeeInstructionRequest
TransferReceiverPaysAppFeeInstructionRequest
TransferSplitAppFeeInstructionRequest
TransferExternalCostGuardRequest

Request body fields

sourceAccountRef
sourceEndpointRef
sourceHoldingRef
destination
valueUnit
amountMinorUnits
acceptedQuote · optional
feeInstruction · optional

Response fields

transfer
replay

Contract notes

feeInstructionKindsrequest_application_fee · request_external_cost_guard

feeInstructionBearerssender_pays · application_pays · receiver_pays · split

feeInstructionExternalCostGuardKindsprovider_fee · gas_fee

externalCostGuardmax_provider_or_gas_cost_over_assessed_runtime_material

receiverPaidAppFeegross_receiver_entitlement_minus_app_fee_net_receiver_credit

splitAppFeeone_app_fee_evidence_line_split_into_one_debit_leg_plus_receiver_withholding_leg

idempotencyMaterialIncludesfee-instruction branch tokens

Sharp edges

Creation returns acceptance, not completion. Follow the stage ladder with the status read; a transfer is done only at a terminal stage.
Replaying the same Idempotency-Key with the same material returns the original result; the same key with different material is a conflict, not a second transfer.

Wire receipt

Captured from the real gateway by the scenario suite; nothing here is composed by hand.

Acceptance is not completion; the response hands you a transfer on its ladder, not a finished move.

Request

POST /v1/transfers
Authorization: Bearer ak_test_…
Idempotency-Key: 1cceab1a-0c3b-4a33-b894-bc6d322bb4f1
Content-Type: application/json

{
  "sourceAccountRef": "1baa9144-8a36-3fb5-bfab-395db835f1ae",
  "sourceEndpointRef": "23f410d0-11b3-3cb0-aaa8-911e90aa2f2b",
  "sourceHoldingRef": "fcc8c901-938d-343b-ac27-497cfa374333",
  "destination": {
    "kind": "internal-endpoint",
    "accountRef": "281b43e7-a6c6-34b6-a488-15266d29d607",
    "endpointRef": "2638f318-9348-3985-aea2-1819b9864dd0",
    "holdingRef": "99869eff-193b-3006-a0cc-785174320c13"
  },
  "valueUnit": {
    "kind": "fiat",
    "currency": "NGN"
  },
  "amountMinorUnits": "4000"
}

Response · 202

{
  "status": 202,
  "body": {
    "transfer": {
      "value": {
        "transferRef": "6b1afc56-788b-3925-8bdb-46b29e36ed85",
        "requestedAt": "2026-07-11T05:20:22.313116Z",
        "decidedAt": "2026-07-11T05:20:22.313116Z",
        "stage": "PrincipalReserved",
        "revision": 2,
        "sourceAccountRef": "1baa9144-8a36-3fb5-bfab-395db835f1ae",
        "sourceEndpointRef": "23f410d0-11b3-3cb0-aaa8-911e90aa2f2b",
        "sourceHoldingRef": "fcc8c901-938d-343b-ac27-497cfa374333",
        "destination": {
          "kind": "internal-endpoint",
          "accountRef": "281b43e7-a6c6-34b6-a488-15266d29d607",
          "endpointRef": "2638f318-9348-3985-aea2-1819b9864dd0",
          "holdingRef": "99869eff-193b-3006-a0cc-785174320c13"
        },
        "valueUnit": {
          "kind": "fiat",
          "currency": "NGN"
        },
        "amountMinorUnits": "4000",
        "requestedBy": "086f004e-d82b-3a74-bb5b-13ef88231870",
        "materialFingerprint": "fp:transfer-initiation-material:d1efc4619f788b940e8e0e96f60f72944cf2c9207b5c56fbfd74f67245373843"
      },
      "freshness": "Current",
      "visibility": "Full",
      "evidence": [
        {
          "receiptRef": "086f004e-d82b-3a74-bb5b-13ef88231870",
          "source": "VaeRuntime"
        }
      ]
    }
  },
  "evidence": [
    {
      "receiptRef": "086f004e-d82b-3a74-bb5b-13ef88231870"
    }
  ]
}

captured 2026-07-11 · gateway 0.1.0 · Money moves · Create the transfer

Replay receipt

Byte-identical material under the same key replays the original answer; nothing moves twice.

Request

POST /v1/transfers
Authorization: Bearer ak_test_…
Idempotency-Key: 3327eb0c-8271-488f-8ef1-8749de14ea16
Content-Type: application/json

{
  "sourceAccountRef": "6171c20d-a937-3fbc-a73c-a30eb8f1f3f6",
  "sourceEndpointRef": "010dc983-ac6f-3cdb-95ca-06249e71db2b",
  "sourceHoldingRef": "39b4d418-e763-3d73-b20f-a1a98353668f",
  "destination": {
    "kind": "internal-endpoint",
    "accountRef": "6e36c5cf-3801-3ff2-bfd4-19429d5f2bf9",
    "endpointRef": "ff2d2a3d-ecea-39b3-b346-ddd8dff23e3b",
    "holdingRef": "ecb7bfd0-ec25-34ca-9fef-197a7942f9a9"
  },
  "valueUnit": {
    "kind": "fiat",
    "currency": "NGN"
  },
  "amountMinorUnits": "500"
}

Response · 202

{
  "status": 202,
  "body": {
    "replay": {
      "intakeRef": "operation-ingress-intake:2346d9c4-b444-385c-878e-3c9a0fb5a847",
      "envelopeRef": "2346d9c4-b444-385c-878e-3c9a0fb5a847",
      "occurrence": "ReplayAccepted",
      "transferRef": "733fa4f6-ddb5-3e1e-a8b4-84d44b48ca8b"
    }
  },
  "evidence": []
}

captured 2026-07-11 · gateway 0.1.0 · The gate holds · Same key, same material

Refused requests

Refusals are stated as plainly as capabilities; these were captured live, the same way.

The same Idempotency-Key with different material is a conflict, not a second transfer.

Request

POST /v1/transfers
Authorization: Bearer ak_test_…
Idempotency-Key: 3327eb0c-8271-488f-8ef1-8749de14ea16
Content-Type: application/json

{
  "sourceAccountRef": "6171c20d-a937-3fbc-a73c-a30eb8f1f3f6",
  "sourceEndpointRef": "010dc983-ac6f-3cdb-95ca-06249e71db2b",
  "sourceHoldingRef": "39b4d418-e763-3d73-b20f-a1a98353668f",
  "destination": {
    "kind": "internal-endpoint",
    "accountRef": "6e36c5cf-3801-3ff2-bfd4-19429d5f2bf9",
    "endpointRef": "ff2d2a3d-ecea-39b3-b346-ddd8dff23e3b",
    "holdingRef": "ecb7bfd0-ec25-34ca-9fef-197a7942f9a9"
  },
  "valueUnit": {
    "kind": "fiat",
    "currency": "NGN"
  },
  "amountMinorUnits": "600"
}

Response · 400

{
  "status": 400,
  "problem": {
    "kind": "InvalidInput",
    "status": 400,
    "code": "invalid-Input",
    "message": "idempotent ingress intake cannot change the request envelope for an existing identity",
    "evidence": []
  },
  "evidence": []
}

captured 2026-07-11 · gateway 0.1.0 · The gate holds · Same key, different material

Five thousand against a five-hundred balance; the reservation is denied and the record says why.

Request

POST /v1/transfers
Authorization: Bearer ak_test_…
Idempotency-Key: 97b8c10b-c5a5-43ee-9a3a-75f66f001c2f
Content-Type: application/json

{
  "sourceAccountRef": "6171c20d-a937-3fbc-a73c-a30eb8f1f3f6",
  "sourceEndpointRef": "010dc983-ac6f-3cdb-95ca-06249e71db2b",
  "sourceHoldingRef": "39b4d418-e763-3d73-b20f-a1a98353668f",
  "destination": {
    "kind": "internal-endpoint",
    "accountRef": "6e36c5cf-3801-3ff2-bfd4-19429d5f2bf9",
    "endpointRef": "ff2d2a3d-ecea-39b3-b346-ddd8dff23e3b",
    "holdingRef": "ecb7bfd0-ec25-34ca-9fef-197a7942f9a9"
  },
  "valueUnit": {
    "kind": "fiat",
    "currency": "NGN"
  },
  "amountMinorUnits": "5000"
}

Response · 200

{
  "status": 200,
  "body": {
    "transfer": {
      "value": {
        "transferRef": "a2acbd92-21e4-3342-9006-3ff695be5458",
        "requestedAt": "2026-07-11T05:20:22.808056Z",
        "decidedAt": "2026-07-11T05:20:22.808056Z",
        "stage": "ReservationDenied",
        "revision": 1,
        "sourceAccountRef": "6171c20d-a937-3fbc-a73c-a30eb8f1f3f6",
        "sourceEndpointRef": "010dc983-ac6f-3cdb-95ca-06249e71db2b",
        "sourceHoldingRef": "39b4d418-e763-3d73-b20f-a1a98353668f",
        "destination": {
          "kind": "internal-endpoint",
          "accountRef": "6e36c5cf-3801-3ff2-bfd4-19429d5f2bf9",
          "endpointRef": "ff2d2a3d-ecea-39b3-b346-ddd8dff23e3b",
          "holdingRef": "ecb7bfd0-ec25-34ca-9fef-197a7942f9a9"
        },
        "valueUnit": {
          "kind": "fiat",
          "currency": "NGN"
        },
        "amountMinorUnits": "5000",
        "requestedBy": "1d564c47-4674-3046-a8ec-b44fc3b23443",
        "materialFingerprint": "fp:transfer-initiation-material:ebcab3ad801aa12ef30b791c89c686b0e26f5dfc2ae175ca120047bc249e2340",
        "denialReason": "InsufficientAvailableBalance"
      },
      "freshness": "Current",
      "visibility": "Full",
      "evidence": [
        {
          "receiptRef": "1d564c47-4674-3046-a8ec-b44fc3b23443",
          "source": "VaeRuntime"
        }
      ]
    }
  },
  "evidence": [
    {
      "receiptRef": "1d564c47-4674-3046-a8ec-b44fc3b23443"
    }
  ]
}

captured 2026-07-11 · gateway 0.1.0 · The gate holds · More than you have

Create a transfer

Key capabilities

Request body fields

Response fields

Contract notes

Sharp edges

Wire receipt

Replay receipt

Refused requests

See also