USDReceipt API

Request body

Field	Type		Description
name	string	required	Label for this key (e.g. "My Agent")
mode	string		test (default) or live

Response 201

{
  "ok": true,
  "api_key": {
    "id": "key_abc123",
    "name": "My Agent",
    "scope": "user",
    "mode": "test",
    "key": "usdr_test_a1b2c3d4..."
  },
  "message": "Store this key securely — it will not be shown again."
}

Response 200

{
  "ok": true,
  "api_keys": [
    {
      "id": "key_abc123",
      "name": "My Agent",
      "scope": "user",
      "mode": "test",
      "is_active": true,
      "created_at": "2026-05-10T12:00:00Z",
      "last_used_at": "2026-05-10T14:30:00Z"
    }
  ]
}

Immediately invalidates the key. Any agent or service using it will receive 401 UNAUTHORIZED.

Response 200

{ "ok": true }

Request body

Field	Type		Description
address	string	required	Ethereum address (0x...)
label	string		Optional label

Response 201

{
  "ok": true,
  "wallet": {
    "id": "wal_abc123",
    "address": "0x742d35Cc...",
    "network": "ethereum",
    "label": "Main wallet",
    "is_verified": false
  }
}

Returns all wallets registered to your account.

Response 200

{
  "ok": true,
  "wallets": [ ... ]
}

Removes a wallet. Fails with WALLET_HAS_ACTIVE_REQUESTS if the wallet has open payment requests.

Response 200

{ "ok": true }

Prove you own a wallet by signing a challenge message. Two-step flow:

Step 1: Get the challenge message:

GET /api/v1/wallets/{id}/challenge
// Response: { "ok": true, "message": "Sign this to verify..." }

Step 2: Sign the message with your Ethereum wallet and submit:

Field	Type		Description
signature	string	required	The personal_sign signature of the challenge message

Response 200

{ "ok": true, "wallet": { "is_verified": true, ... } }

Challenges expire after 5 minutes and are single-use.

Queries Ethereum for recent incoming USDT transfers to this wallet. Automatically cross-references against your open payment requests.

Parameter	In	Type	Description
id	path	string	Wallet ID
blocks	query	integer	How many blocks back to scan (default 50000, max 500000)

Response 200

{
  "ok": true,
  "wallet_address": "0x742d...",
  "blocks_scanned": 50000,
  "transfers": [
    {
      "tx_hash": "0xabc...",
      "from_address": "0x123...",
      "amount_usdt": "250.0",
      "already_used": false,
      "matching_request": { "id": "chk_xyz", "title": "Premium Plan" }
    }
  ]
}

Rate limited to 10 requests/minute per user to protect RPC quota.

Request body

Field	Type		Description
amount_usdt	string	required	Amount in USDT or USDC
recipient_address	string	required	Your wallet address
token	string		Token to accept: USDT or USDC (default: USDT)
title	string		Display title
memo	string		Additional notes
collect_buyer_info	boolean		Require buyer name/email
expires_at	datetime		Optional expiration

Response 201

{
  "ok": true,
  "checkout": {
    "id": "chk_abc123",
    "url": "https://usdreceipt.xyz/pay/chk_abc123",
    "amount_usdt": "49.99",
    "status": "open"
  }
}

Returns all verified payment receipts for a checkout.

Response 200

{
  "ok": true,
  "receipts": [ ... ]
}

Request body

Field	Type		Description
recipient_address	string	required	Your wallet address
line_items	array	required	At least one line item
token	string		Token to accept: USDT or USDC (default: USDT)
title	string		Invoice title
client_name	string		Client name for the invoice
client_email	string		Client email (receipt will be sent here)
due_date	date		Payment due date (YYYY-MM-DD)

Line item format:

{
  "description": "Smart contract audit",
  "quantity": 1,
  "unit_price_usdt": "2500"
}

Response 201

{
  "ok": true,
  "invoice": {
    "id": "inv_abc123",
    "invoice_number": "INV-2026-0001",
    "url": "https://usdreceipt.xyz/invoice/inv_abc123",
    "amount_usdt": "2500",
    "status": "open"
  }
}

Submit an Ethereum transaction hash. USDReceipt verifies on-chain that the correct amount of the selected token (USDT or USDC) was sent to the correct address. Accepts payments within 1% of the requested amount.

No authentication required — this endpoint is public so buyers can submit their own transaction hashes.

Request body

Field	Type		Description
tx_hash	string	required	Ethereum transaction hash (0x + 64 hex chars)
client_name	string		Buyer name (required if collect_buyer_info is on)
client_email	string		Buyer email (required if collect_buyer_info is on)

Responses

201 Payment verified — receipt created

202 Transaction found but waiting for block confirmations

400 Verification failed (see error code)

Public endpoint — returns details of a checkout or invoice. Includes line_items for invoices.

Returns all checkouts and invoices for the authenticated user.

Cancels an open checkout or invoice. Cannot void a payment request that's already been paid.

Public endpoint — returns receipt details including tx_hash, block_number, sender/receiver addresses, and amount_usdt.

PDF version available at: /receipt/{id}/pdf

Returns all verified receipts for the authenticated user.

Downloads all receipts as a CSV file. Useful for accounting, tax reporting, or importing into spreadsheets.

curl -O https://usdreceipt.xyz/api/v1/receipts/export/csv \
  -H "Authorization: Bearer usdr_YOUR_KEY"

Returns your business profile settings.

Request body (all fields optional)

Field	Type	Description
business_name	string	Your business name
business_address	string	Business address
tax_id	string	Tax ID / EIN / VAT number
tax_label	string	Label for tax line (e.g. "Sales Tax", "VAT")
tax_rate	string	Tax rate as percentage (0–100)