Onchain OS A2A Payment

onchainos payment a2a-pay

paymentId

Skill Routing

onchainos payment a2a-pay

okx-x402-payment

okx-agentic-wallet

onchainos payment a2a-pay

Triggers

• "create payment link", "create a2a payment", "generate payment", "create payment authorization"
• "pay paymentId", "pay a2a_...", "pay this link", "settle this payment"
• "payment status", "a2a payment status", "check payment status", "where is my payment"

Pre-flight Checks

create

pay

ensure_tokens_refreshed

not logged in

create

pay

onchainos wallet status

• Logged in → proceed.
• Not logged in → ask the user to log in via

  onchainos wallet login

  (AK login, no email) or

  onchainos wallet login <email>

  (OTP login). Do NOT attempt to sign without a live session.

status

Operation Flow

Seller — Create a Payment Link (

a2a-pay create

)

• Required:

  --amount

  (decimal token amount, e.g.

  "0.01"

  ),

  --symbol

  (e.g.

  "USDT"

  ),

  --recipient

  (0x... EVM address — seller wallet)
• Optional:

  --description

  ,

  --realm

  ,

  --expires-in

  (seconds, default 1800)

1. Run pre-flight (see above) — the CLI requires a live session.
2. Shell out:
   bash

   onchainos payment a2a-pay create \
     --amount <amount> --symbol <symbol> --recipient <recipient> \
     [--description <text> --realm <domain> --expires-in <seconds>]

3. Parse the response — only

   payment_id

   and

   deliveries.url

   (optional) are present. The CLI no longer returns

   amount

   /

   currency

   ; the skill echoes the seller's input args back for display.
4. Display to the user:

   Payment link created. • paymentId:

   <id>

   • Amount:

   <amount input> <symbol input>

   (decimal as you submitted) • Recipient:

   <recipient input>

   • Share with buyer:

   <deliveries.url>

   (if returned by the server) or

   paymentId=<id>

5. Suggest next: poll status anytime with

   onchainos payment a2a-pay status --payment-id <id>

   once the buyer is expected to have paid.

Buyer — Pay a Payment Link (

a2a-pay pay

)

paymentId

Trust model: the buyer signs the seller's challenge as-is. Verifying that the challenge matches what the buyer agreed to pay is the upstream caller's responsibility: the user (or the upstream skill) MUST cross-check the seller's

paymentId

/

deliveries.url

against their out-of-band agreement (chat, task spec, prior negotiation) before calling this skill. Once the skill is invoked, it will sign the on-server challenge.

Step 1 — Sign and Submit

onchainos payment a2a-pay pay --payment-id <paymentId>

{
  "payment_id": "a2a_xxx",
  "status": "<status>",
  "tx_hash": "<hash or null>",
  "valid_after": 0,
  "valid_before": 1746000000,
  "signature": "0x..."
}

Step 2 — Auto-poll Status to Terminal

• Non-terminal (poll):

  pending

  ,

  settling

• Terminal (stop):

  completed

  ,

  failed

  ,

  expired

  ,

  cancelled

status

onchainos payment a2a-pay status --payment-id <paymentId>

• As soon as a terminal status is observed → render full result (status + tx_hash + block_number) and stop.
• If 60 seconds elapse and the status is still non-terminal → return the current

  status

  plus the paymentId, and tell the user: "Status is still

  <status>

  after 60s; you can run

  status

  again later."

completed

<tx_hash>

<block_number>

failed

expired

cancelled

Status — Query Payment State (

a2a-pay status

)

paymentId

1. Run:
   bash

   onchainos payment a2a-pay status --payment-id <paymentId>

2. Map the returned

   status

   to a human-readable line:

   status	Meaning	Display
   pending	Awaiting buyer signature	"⏳ Awaiting buyer signature."
   settling	Credential received, settling on-chain	"🔄 Settling on-chain (credential submitted, awaiting confirmation)."
   completed	Confirmed on-chain	"✅ Confirmed on-chain. tx_hash: <tx_hash> block: <block_number> fee: <fee_decimal> <fee_symbol> "
   failed	Payment failed	"❌ Failed. (include the server-provided reason if any)"
   expired	Expired before settlement	"⌛ Expired before settlement."
   cancelled	Seller cancelled	"🚫 Cancelled by seller."

3. Rendering the fee. The CLI returns

   fee_amount

   as a top-level string in minimal units (and

   fee_bps

   as the basis-points used). To compute

   <fee_decimal>

   , look up the token decimals in the table under "Amount Display Rules". For

   <fee_symbol>

   , reuse the

   --symbol

   the seller passed to

   create

   for the same

   paymentId

   — the upstream caller (or the seller flow that issued the link) is the source of truth for the token symbol; the

   status

   response itself does not echo it back. If neither is available, display

   fee_amount

   minimal units as-is.
4. Suggest next:

   • pending

     /

     settling

     → "Check again in a few moments" or wait briefly and re-run

     status

     .

   • completed

     → recommend

     okx-agentic-wallet

     to verify the buyer's post-payment balance delta.

   • failed

     → recommend checking buyer balance via

     okx-agentic-wallet

     , and if

     tx_hash

     is present, inspect it via

     okx-security tx-scan

     .

Cross-Skill Workflows

Workflow A — Sub-skill called from an upstream agent flow (most common)

paymentId

paymentId

1. <upstream caller>     verifies paymentId matches the buyer's agreed terms → hands off paymentId
       ↓
2. okx-a2a-payment (this skill)  onchainos payment a2a-pay pay → auto-poll status → display terminal state
       ↓
3. okx-agentic-wallet    optional: onchainos wallet balance to see post-payment delta

Workflow B — Seller manually creates a payment link

1. okx-a2a-payment create   → paymentId + deliveries.url
2. Seller shares paymentId (and optionally deliveries.url) with the buyer out-of-band (chat / QR / message)
3. Buyer cross-checks the paymentId / deliveries.url against the seller's quoted terms, then runs Workflow A starting from step 2 with the received paymentId

Workflow C — Payment failure triage

1. okx-a2a-payment status                 → expired / failed / cancelled
2. Branch on terminal state:
   - expired   → ask seller to create a new link
   - failed    → check buyer balance via okx-agentic-wallet; inspect tx_hash via okx-security tx-scan if present
   - cancelled → contact seller out-of-band

Upstream Routing — Avoiding

create

Loops

付款

pay

payment

create

buyer: "I want to pay"        → seller create → returns paymentId_A
buyer pays via this skill, then sends:
buyer: "payment successful"   → seller matches "payment" → create AGAIN → paymentId_B (wrong)

create

1. Detect existing paymentId in the incoming message. If the buyer's message contains an

   a2a_...

   id (or a

   deliveries.url

   you previously issued), route to

   okx-a2a-payment status

   for that id. Do NOT call

   create

   .
2. Disambiguate intent beyond keywords. Map upstream intents to commands:

   Buyer says	Intent	Route to
   "I want to pay" / "请付款" / "怎么付" / "give me a link"	request-invoice	create
   "paid" / "payment successful" / "已付" / "已转账" / contains a paymentId or tx hash	payment-receipt	status (or no-op if already terminal)
   "cancel" / "refund"	cancel/refund	out of scope for this skill

   Plain keyword matching on

   付款

   /

   pay

   /

   payment

   is not enough — both request-invoice and payment-receipt utterances contain those tokens.
3. Track per-conversation order state upstream. Once

   create

   issues a paymentId for a given (buyer, order) context, the upstream agent must remember that paymentId in its own conversation / order state and mark the order as "awaiting payment". Subsequent buyer messages in that context default to

   status

   against the remembered paymentId until either the payment reaches a terminal state or the user explicitly asks for a new order.
4. Idempotency on

   create

   . Before issuing a new

   create

   , the upstream agent must check its own state: if a non-terminal paymentId already exists for the same buyer / order context, reuse it instead of creating a new one.

Amount Display Rules

amount

fee_amount

1e18

<minimal> <symbol>

unknown decimals — please double-check the seller-provided amount

Edge Cases

onchainos wallet status

onchainos wallet login

paymentId

payment ... not payable

paymentId

pay

pending

settling

Status is still <status> after 60s; you can run status again later

errorMessage

pay

status

--symbol

--expires-in

status

expired

Command Index

onchainos payment a2a-pay create

onchainos payment a2a-pay pay

onchainos payment a2a-pay status

CLI Command Reference

1.

onchainos payment a2a-pay create

onchainos payment a2a-pay create \
  --amount <decimal> --symbol <symbol> --recipient <address> \
  [--description <text>] [--realm <domain>] [--expires-in <seconds>]

--amount

"50"

"0.01"

--symbol

"USDT"

--recipient

to

--description

--realm

provider.example.com

--expires-in

payment_id

deliveries

url

2.

onchainos payment a2a-pay pay

onchainos payment a2a-pay pay --payment-id <id>

--payment-id

payment_id

status

tx_hash

valid_after

valid_before

signature

3.

onchainos payment a2a-pay status

onchainos payment a2a-pay status --payment-id <id>

--payment-id

payment_id

status

tx_hash

block_number

block_timestamp

fee_amount

fee_bps

Quickstart

# Seller — create a payment link
onchainos payment a2a-pay create \
  --amount 0.01 --symbol USDT \
  --recipient 0xSellerWalletAddress
# → { "payment_id": "a2a_xxx", "deliveries": { "url": "..." } }

# Buyer — pay (signs the on-server challenge as-is; trust delegated to upstream)
onchainos payment a2a-pay pay --payment-id a2a_xxx

# Either side — query status (skill auto-polls this for ~60s after pay if non-terminal)
onchainos payment a2a-pay status --payment-id a2a_xxx