Pay a PayMe handle from an agent

Wallet-capable agents can pay an active Hilt PayMe recipient through one public HTTP endpoint:

POST https://api.hilt.so/v1/pay-me/payments

The first request resolves the verified X handle, pins the recipient and payment terms, and returns an HTTP 402 Payment Required response with a Machine Payments Protocol (MPP) charge challenge. The agent signs the advertised Solana transaction and retries the same request with Authorization: Payment. No payer PayMe account or Hilt API key is required.

MPP is the HTTP payment-authentication protocol used by this PayMe action. It is not a chain, token, wallet, or Hilt Pay API /v1/access route.

PayMe MPP pays a verified recipient and returns a payment receipt. It does not grant access to an API or protected resource.

Request a payment challenge

curl --request POST \
  --url https://api.hilt.so/v1/pay-me/payments \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: agent-payment-018f6b7e' \
  --data '{
    "xHandle": "recipient",
    "amount": "1",
    "asset": "USDC",
    "note": "Design work"
  }'

The asset may be SOL or USDC. amount is the exact amount the recipient should receive. The optional Idempotency-Key lets the caller safely reuse the same challenge for the same request. The unpaid response has status 402, includes WWW-Authenticate: Payment ..., and returns a machine-readable summary:

{
  "type": "https://www.hilt.so/problems/payment-required",
  "title": "Payment required",
  "detail": "Sign the advertised MPP charge and retry this request with Authorization: Payment.",
  "payment": {
    "id": "mpp_payment_example",
    "status": "payment_required",
    "protocol": "mpp",
    "recipient": {
      "xHandle": "recipient",
      "identityVerified": true,
      "walletVerified": true
    },
    "asset": {
      "symbol": "USDC",
      "decimals": 6
    },
    "quote": {
      "recipientAmount": "1",
      "hiltFeeAmount": "0.020409",
      "buyerAmount": "1.020409",
      "platformFeeBps": 200,
      "feePaidBy": "payer"
    }
  },
  "challenge": {
    "method": "solana",
    "intent": "charge"
  }
}

The sender funds the displayed total. The verified PayMe recipient receives the requested amount and Hilt receives its flat 2% share from the total paid by the sender. Both transfers are contained in one buyer-signed Solana transaction.

Sign and retry

Use an MPP-compatible Solana client to validate the challenge, build the transaction, and sign it with the payer wallet. Retry the same URL and JSON body with the returned authorization credential:

POST /v1/pay-me/payments HTTP/1.1
Host: api.hilt.so
Content-Type: application/json
Authorization: Payment <MPP credential>

{
  "xHandle": "recipient",
  "amount": "1",
  "asset": "USDC",
  "note": "Design work"
}

Hilt verifies that the credential belongs to the challenged payment, submits and confirms the exact transaction, records the PayMe receipt, and returns 200 OK. The response also exposes the standard Payment-Receipt header and the finalized signature in X-Payment-Settlement-Signature.

{
  "payment": {
    "id": "mpp_payment_example",
    "status": "completed",
    "protocol": "mpp",
    "receipt": {
      "receiptNumber": "HILT-...",
      "network": "solana-mainnet",
      "payerWallet": "...",
      "recipientXHandle": "recipient",
      "recipientWallet": "...",
      "tokenSymbol": "USDC",
      "recipientAmount": "1",
      "hiltFeeAmount": "0.020409",
      "checkoutAmount": "1.020409",
      "txSignature": "...",
      "solscanUrl": "https://solscan.io/tx/...",
      "completedAt": "..."
    }
  }
}

Read payment status

The payment summary and receipt can also be read by public payment ID:

GET https://api.hilt.so/v1/pay-me/payments/{paymentId}

Use this after a network interruption or when the signed retry response was not received. A finalized payment remains tied to one receipt and one Solana transaction signature.

Safety and retry rules

Validate the complete MPP challenge before signing.
Keep the request body unchanged when retrying with the payment credential.
Reuse one unpredictable idempotency key for retries of the same intended payment.
Do not treat the initial 402 response as a completed payment.
Do not pay again when a response is interrupted. Read the payment status first.
Never expose a seed phrase or private key to Hilt. The payer wallet remains the signing authority.
Do not use this route as proof of API access. PayMe payments issue receipts; Hilt Pay API /v1/access manages paid-resource entitlements and atomic usage.

Choose the right agent flow

Need	Use
A wallet-capable agent should pay a verified PayMe handle directly	This MPP payment action
An AI client should prepare a payment and open a browser wallet-approval page	PayMe MCP connector
A seller should charge for an API result or protected resource	Hilt Pay API
A merchant wants a no-account hosted checkout and simple unlock	Direct Checkout

​Pay a PayMe handle from an agent

​Request a payment challenge

​Sign and retry

​Read payment status

​Safety and retry rules

​Choose the right agent flow

​Reference

Pay a PayMe handle from an agent

Request a payment challenge

Sign and retry

Read payment status

Safety and retry rules

Choose the right agent flow

Reference