Core Objects & APIs

1. Core Objects

TransferSession

A TransferSession represents a request to move funds under specific constraints.

It is created by the platform backend and consumed by the Swype-hosted browser flow.

Key properties

• id – unique identifier

• direction – deposit or withdrawal

• destination_address

• destination_chain

• accepted_assets

• amount_constraints (optional)

• expires_at

• status – created | expired | consumed

Notes

• Transfer sessions are short-lived and single-use

• Destination constraints are immutable once created

• A session cannot execute without a valid allowance

Transfer

A Transfer represents the execution of a deposit or withdrawal.

It is created by Swype after a transfer session is consumed and progresses through a defined lifecycle.

Key properties

• id

• transfer_session_id

• direction

• amount

• asset

• chain

• status – processing | completed | failed

• created_at

• completed_at (when applicable)

Notes

• Swype is the system of record for transfer state

• Platforms should update balances only on completed

Allowance

An Allowance represents permission for Swype to coordinate transfers on behalf of a platform.

Scope

• per user

• per platform

• per stablecoin app

Key properties

• platform_id

• source (stablecoin app)

• limit

• remaining

• expires_at

Notes

• Allowances are created and approved inside the stablecoin wallet

• Platforms cannot create, modify, or expand allowances

• If an allowance is revoked, subsequent transfers will fail

WebhookEvent

A WebhookEvent notifies the platform of transfer lifecycle changes.

Key properties

• id

• type

• created_at

• data (transfer payload)

Event types

• transfer.processing

• transfer.completed

• transfer.failed

Notes

• Events may be delivered more than once

• Platforms must deduplicate by event ID

• Webhooks are the canonical source of transfer state

2. API Endpoints

Create a transfer session

POST /v1/transfer_sessions

Creates a new transfer session for a deposit or withdrawal.

Required inputs

• direction

• destination_address

• destination_chain

• accepted_assets

Optional inputs

• amount_constraints

• metadata

• return_urls

Response

• transfer_session_id

• swype_url

• expires_at

Fetch a transfer (optional)

GET /v1/transfers/{id}

Returns the current state of a transfer.

Notes

• Intended as a fallback if webhooks are missed

• Webhooks remain the source of truth