USDT Pay

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

USDT Pay lets Acquirers accept customer USDT payments without taking custody of customer funds. The customer pays on-chain from their own wallet to a one-time deposit address. t-0 verifies the payment and tracks the payment intent through authorization and settlement.

Four roles take part:

Acquirer — owns the merchant relationship, creates the payment intent, and receives settlement.
Issuer — creates payment instructions, allocates one-time deposit addresses, watches the blockchain, and settles USDT.
Liquidity Provider (LP) — in fiat settlement mode, receives USDT from the Issuer and pays local fiat to the Acquirer over bank rails.
t-0 — routes messages, owns payment-intent state, maintains the LP standing quotes, and verifies on-chain settlement.

Each Acquirer has one settlement mode, fixed at onboarding. In USDT settlement, the Issuer settles USDT on-chain to the Acquirer’s wallet. In fiat settlement, the Issuer settles USDT to the LP, and the LP settles local fiat to the Acquirer.

How It Works

Mon, 01 Jan 0001 00:00:00 +0000

USDT Pay lets an Acquirer accept a customer’s on-chain USDT payment and receive verified settlement in the mode configured at onboarding. The customer pays from their own wallet to a one-time deposit address. The Acquirer does not take custody of customer funds, and the QR only carries the chain-native payment URI into the wallet.

The flow starts when the Acquirer creates a payment intent. t-0 asks the Issuer for payment instructions, returns a deposit address and wallet payload, verifies the Issuer’s payment report, authorizes the sale, and coordinates settlement. In USDT settlement, the Issuer settles on-chain to the Acquirer’s wallet. In fiat settlement, the Issuer settles USDT to the LP, and the LP pays local fiat to the Acquirer over bank rails.

Fiat Settlement

Mon, 01 Jan 0001 00:00:00 +0000

This document specifies the fiat settlement path: the path on which a merchant’s Acquirer is settled in its local currency through a Liquidity Provider, while the customer pays USDT on-chain. It covers the inter-party protocol, the money movements, the settlement guarantee, and the failure handling. It is written for leaders, product managers, and architects across the four participants (t-0, the Acquirer, the Issuer, and the LP). The alternative mode, in which the Acquirer is settled in USDT on-chain, is out of scope here except for a single contrast that clarifies the boundary.

Integration Guidance

Mon, 01 Jan 0001 00:00:00 +0000

You integrate with USDT Pay by implementing the protocol over the t-0 network. Communication uses Connect RPC, so every method is available over gRPC and over HTTP/JSON with the same request and response types. Every request is signed (see Request Authentication).

Your role determines which services you call and which callbacks you implement:

Acquirer — call AcquirerService (get a quote, create a payment intent, confirm fiat receipt); implement AcquirerCallbackService (authorization and settlement events).
Issuer — call IssuerService (payment received, settlement sent, expiry); implement IssuerCallbackService (create payment instructions).
Liquidity Provider — call LpService (publish and withdraw quotes, fiat settlement sent); implement LpCallbackService (execute quote).

The service and message definitions are in the API Reference, generated from acquirer.proto, issuer.proto, lp.proto, and types.proto. Generate your client and server stubs from those definitions.

Idempotency and Reliability

Mon, 01 Jan 0001 00:00:00 +0000

Connections drop and requests time out. t-0 and the roles deliver every state-changing message at least once, retrying with backoff until the receiver acknowledges, so your endpoint can receive the same request more than once. Idempotency makes those retries safe: a repeat with the same key returns the original result and causes no further side effect.

At-least-once delivery plus idempotent receivers produces exactly-once processing without a coordination protocol. Both t-0 and every role must hold their side of the contract.

Acquirer

Mon, 16 Jun 2025 12:09:09 +0200

AcquirerCallbackService

Acquirer-implemented callbacks t-0 pushes — authorization, settlement progress, and expiry. Delivered at least once and deduped on the t-0 id.

Method Name	Request Type	Response Type	Description
PaymentAuthorized	PaymentAuthorizedRequest	PaymentAuthorizedResponse	Tells the merchant the sale is approved; from here the Issuer is obligated to settle.
SettlementInitiated	SettlementInitiatedRequest	SettlementInitiatedResponse	Pre-notice that the LP sent a fiat bank transfer, naming the reference to expect.
SettlementCompleted	SettlementCompletedRequest	SettlementCompletedResponse	Settlement verified on-chain as reached the Acquirer (USDt mode only); lists the intents it clears.
PaymentExpired	AcquirerPaymentExpiredRequest	AcquirerPaymentExpiredResponse	Intent expired with no payment; clear the pending order and drop the QR.

Issuer

Mon, 16 Jun 2025 12:09:09 +0200

IssuerCallbackService

Issuer-implemented endpoint t-0 calls to reserve deposit addresses and obtain the renderable QR payloads for an intent.

Method Name	Request Type	Response Type	Description
CreatePaymentInstructions	CreatePaymentInstructionsRequest	CreatePaymentInstructionsResponse	Reserves one deposit address per supported chain and returns the renderable QR payloads.

IssuerService

t-0 endpoints the Issuer calls to report on-chain recognition, settlement, and reservation expiry.

Method Name	Request Type	Response Type	Description
PaymentReceived	PaymentReceivedRequest	PaymentReceivedResponse	Reports the customer’s payment seen on-chain and KYT-cleared; the Issuer now owns on-chain risk.
SettlementSent	SettlementSentRequest	SettlementSentResponse	Reports a USDt settlement sent on-chain to the registered destination, for t-0 to verify.
PaymentExpired	IssuerPaymentExpiredRequest	IssuerPaymentExpiredResponse	Confirms the reservation closed with no valid payment and the deposit addresses are released.

Requests And Response Types

Liquidity Provider

Mon, 16 Jun 2025 12:09:09 +0200

LpCallbackService

LP-implemented endpoint t-0 calls to bind the LP to a standing quote’s locked rate for one authorized sale. Fiat mode only.

Method Name	Request Type	Response Type	Description
ExecuteQuote	ExecuteQuoteRequest	ExecuteQuoteResponse	Creates the LP’s firm per-sale obligation at the standing quote’s locked rate.

LpService

t-0 endpoints the LP calls to push and withdraw standing quotes and to report its self-initiated fiat settlements. Fiat mode only.

Shared Types

Mon, 16 Jun 2025 12:09:09 +0200

Requests And Response Types

FiatSettlementDetails

Fiat bank-rails settlement detail shape. Currently unused on the wire: fiat mode has no SettlementCompleted (13) — the Acquirer’s SettlementReceived (12) is terminal — and SettlementInitiated (11) carries these fields inline. Retained as the canonical fiat-settlement detail shape.

Field	Type	Description
lp_id	uint64	t-0’s identifier for the LP that settled; scopes `bank_transfer_ref`.
local_currency	string	ISO 4217 currency code delivered (e.g. COP).
bank_transfer_ref	string	LP-minted reference on the bank-rails transfer.

Common

Mon, 16 Jun 2025 12:09:09 +0200

Requests And Response Types

Decimal

Decimal 123.45 equals to unscaled=12345 and exponent=-2 (e.g. unscaled * 10^exponent, 123.45 = 12345 * 10^-2)

Field	Type	Label	Description
unscaled	int64
exponent	int32

Blockchain

Name	Number	Description
BLOCKCHAIN_UNSPECIFIED	0
BLOCKCHAIN_BSC	10
BLOCKCHAIN_ETH	20
BLOCKCHAIN_TRON	100

Stablecoin

Name	Number	Description
STABLECOIN_UNSPECIFIED	0
STABLECOIN_USDT	10

Scalar Types

Mon, 16 Jun 2025 12:09:09 +0200

Well-Known Types

google.protobuf.Timestamp

A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution.

See google.protobuf.Timestamp documentation.

Request Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Every request between t-0 and a role (Acquirer, Issuer, or LP) is signed. Signing uses an ECDSA signature over a Keccak-256 hash — the same primitives as Ethereum — giving both authentication and message integrity. Both directions are signed: t-0 signs the requests it sends to a role, and each role signs the requests it sends to t-0.

Request signing

Each request carries three headers:

X-Signature — the hex-encoded ECDSA signature of the request body with the timestamp appended.
X-Public-Key — the hex-encoded public key for the signing key. Compressed (33 bytes) or uncompressed (65 bytes); compressed is preferred.
X-Signature-Timestamp — the Unix timestamp in milliseconds used during signing.

To sign a request: take the current Unix timestamp in milliseconds as a 64-bit unsigned integer encoded little-endian, append it to the request body, hash the result with Keccak-256, and sign the hash with the sender’s ECDSA private key.

USDT Pay

Introduction

How It Works

Fiat Settlement

Integration Guidance

Idempotency and Reliability

Acquirer

AcquirerCallbackService link

Issuer

IssuerCallbackService link

IssuerService link

Requests And Response Types link

Liquidity Provider

LpCallbackService link

LpService link

Shared Types

Requests And Response Types link

FiatSettlementDetails link

Common

Requests And Response Types link

Decimal link

Blockchain link

Stablecoin link

Scalar Types

Well-Known Types link

google.protobuf.Timestamp link

Request Authentication

Request signing link

AcquirerCallbackService

IssuerCallbackService

IssuerService

Requests And Response Types

LpCallbackService

LpService

Requests And Response Types

FiatSettlementDetails

Requests And Response Types

Decimal

Blockchain

Stablecoin

Well-Known Types

google.protobuf.Timestamp

Request signing