Atomic Swaps

Bilateral exchange of obligations + payments in a single state-transition. Both sides settle together or neither does.

Need collateral, repo, or rehypothecation? Read Collateralisation — the contingent-contract model, full repo lifecycle, rolls, and rehypothecation chains.

A swap is how two parties exchange obligations and / or payments atomically — both sides settle in a single on-chain transition, or neither does. Swaps are what an activated DealPlan typically compiles down to when value needs to change hands between parties.

One GraphQL gateway, one JWT. Post swap mutations and joined swap reads to $YF_GATEWAY/graphql (api.yieldfabric.com/graphql). Swap mutations return a messageId; poll payments REST until executed is non-null before treating the swap as settled.

What atomic means here

The whole exchange either succeeds together or fails together. No partial-execution state exists.

  • Atomic settlement. Both transfers happen simultaneously or the transaction fails. No intermediate state where one side has paid but not received.
  • No counterparty risk in execution. The chain enforces it. Neither side can settle without the other.
  • Composable structures. Exchange multiple obligations + payments at once — bundle a tranche, swap a portfolio.
  • Immutable audit. The on-chain record is the canonical evidence of what got exchanged and when.

Propose a swap

The initiator describes what they're offering (obligations or payments) and what they expect in return.

curl -X POST $YF_GATEWAY/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($counterpartyExpectedPayments: InitialPaymentsInput) { createSwap(input: { swapId: \"SWAP-2027-Q4-001\", counterparty: \"ENT-buyer-12\", deadline: \"2027-11-10\", initiatorObligationIds: [\"CTR-1\", \"CTR-2\"], counterpartyExpectedPayments: $counterpartyExpectedPayments }) { success swapId messageId } }",
    "variables": {
      "counterpartyExpectedPayments": {
        "denomination": "aud-token-asset",
        "amount": "100",
        "payments": [
          { "oracleAddress": null, "oracleOwner": null, "oracleKeySender": "0", "oracleValueSenderSecret": "0", "oracleKeyRecipient": "0", "oracleValueRecipientSecret": "0", "unlockSender": null, "unlockReceiver": null }
        ]
      }
    }
  }'

Counterparty accepts

The counterparty calls completeSwap with the expected payments. The chain executes both sides atomically.

curl -X POST $YF_GATEWAY/graphql \
  -H "Authorization: Bearer $COUNTERPART_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { completeSwap(input: { swapId: \"SWAP-2027-Q4-001\" }) { success message swapId messageId } }"
  }'

Swap lifecycle

Step
1
Action
Create obligations
Description
Build the obligation structures (self-referential during construction is fine — see Contracts).
Step
2
Action
Accept obligations
Description
Lock the structures so they're ready to swap.
Step
3
Action
Create swap
Description
Initiator proposes the exchange — obligations going out, payments expected back.
Step
4
Action
Complete swap
Description
Counterparty accepts; the chain executes both sides atomically.
Step
5
Action
Settled
Description
On-chain state updated; bitemporal audit record written.

Use cases

  • Securitisation. Sell future payment rights for immediate liquidity. Issuer trades obligation bundle for cash up front.
  • Debt assignment. Transfer loan obligations between parties — original creditor exits, new creditor takes the position.
  • Structured finance. Package composite obligation bundles (tranche A + tranche B) and exchange them as one atomic unit.
  • Liquidity provision. Exchange held obligations for cash on demand.

Example — annuity securitisation

Scenario. Issuer creates future payment obligations totaling 105 AUD over time, and atomically swaps them for an immediate 100 AUD payment from a counterparty. The 5 AUD spread is the counterparty's yield for funding the issuer up front.

Issuer

  • Receives 100 AUD immediately (liquidity).
  • Owes 105 AUD over time (as obligor).

Counterparty

  • Pays 100 AUD upfront.
  • Receives 105 AUD over time (5% yield).

See the full workflow for the end-to-end calls.

Query swaps

List all swaps where the given entity is initiator or counterparty. Includes status, deadline, and the obligation IDs on each side.

curl -X POST $YF_GATEWAY/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetSwaps($entityId: ID!) { swapFlow { coreSwaps { byEntityId(entityId: $entityId) { id swapId status deadline parties { entity { name } role } initiatorObligationIds } } } }",
    "variables": {
      "entityId": "your-entity-id"
    }
  }'

See also

YieldFabric docs(317)