x402 Execute

Prerequisite: Before using any Passport skill, check if kpass is installed by running command -v kpass. If it returns nothing, invoke the passport-setup skill first to install the CLI.

Execute HTTP requests and pay for them with Kite Passport. The account allowance pays first: when no usable session is current, kpass session execute binds the owner's account allowance and pays from it, with no approval request. A session the user approved separately (request-session or attach-session) is used when it is current. The Passport backend handles x402 payment negotiation transparently -- you specify the target URL and the backend negotiates payment with the remote service on your behalf. Execution has a 5-minute timeout: payment settles on the merchant's advertised network -- on mainnet base, Polygon, Avalanche, tempo, solana, Robinhood Chain, or Arc (eip155:5042) -- and a cross-chain routed (or Solana) settlement can take up to ~2 minutes -- a slow response is not a failure until the full timeout is reached. On the dev environment the only settlement chain is Arc testnet (eip155:5042002, Circle USDC) and there is no cross-chain routing -- routed-settlement latency and the routing error codes below do not apply there.

Reference files (read when you need exact detail):

• @references/commands.md — full command reference: every flag, the full JSON output shape, and every error code/message for session execute.
• @references/examples.md — complete worked examples (POST request, GET with custom headers, using a specific session).

When to Use This Skill

• The user asks you to access a paid API or service that requires payment.
• You encounter an HTTP 402 Payment Required response and the user has a Kite Passport session.
• The user asks you to make a request to a URL that you know requires x402 payment.

Prerequisites

Before using this skill, you MUST have:

1. User authenticated -- Use the authenticate-user skill if not logged in.
2. Agent registered -- Use the request-session skill to register the agent (also done automatically by attach-session).
3. Something to pay from -- Usually nothing to do: the account allowance pays, and execute binds it on its own, with no question to the user (kpass allowance status --output json shows what is left, free). Use request-session only when the CLI says the allowance can't pay (see Error Handling) or the user asks for a separate spending session. A session bound with attach-session (e.g. pre-created in the Passport web dashboard) is used as is; do not re-run request-session for it.

If any of these are missing, the command will fail with exit code 3 (auth error). Follow the error message to the appropriate prerequisite skill.

Recurring and shared allowance payments

For a recurring session or account-allowance binding, supply --idempotency-key <unique-operation-id> on every kpass session execute call. Confirm the installed CLI exposes this flag with kpass session execute --help. If it does not, upgrade the CLI before attempting recurring or allowance-backed payments; do not omit the key to work around an older CLI. Keep that key and the exact request input for a transport retry. A genuinely new payment gets a new key; never change the key to work around a pending or unknown outcome.

On recurring_budget_exhausted, stop. Tell the user the reset date and the dashboard link where the owner can raise the allowance; both are in the hint (from reset_at and dashboard_url in the reply). A separate spending session goes through request-session, only after the user's yes. On recurring_payment_unknown, read details.outcome before you act on the error_code, because a merchant failure keeps that same code. details.outcome: "merchant_failed_held" means no retry at all, with the same key or with a new one, because the merchant failed after the payment and the money is held. Give the user the CLI's facts and wait for the result with the CLI's next_command, as Merchant Failed After Payment below sets out. Otherwise follow the exit 7 row under Error Handling: retry once later with the CLI's next_command (same key), then stop. On execute_in_progress, stop and ask the owner to reconcile the original operation. On recurring_request_conflict, restore the original request rather than generating another key. Never switch agents or sessions on your own to get around an exhausted shared budget. The allowance currently supports only direct exact-scheme USDC x402 on the configured network: Base mainnet (eip155:8453) on staging/prod or Arc testnet (eip155:5042002) on dev. It does not authorize shopping, cards, A2A, Router top-ups, or bridges. On allowance_disabled, stop using this allowance; any separate session needs its own explicit owner approval. On allowance_cancelled, the owner cancelled the allowance this agent was bound to. The CLI binds once to the owner's current allowance and retries the same payment with the same idempotency key. Do not run the bind yourself. If the retry still fails, stop and tell the user the owner cancelled the allowance.

Defaults (Do Not Ask the User Unless They Specify Otherwise)

Shell-safe substitution — MANDATORY: --url, --headers, and --body commonly carry dynamic values (a user-provided or catalog target URL, a constructed JSON body). Never splice these into the command as bare text or inside double quotes — double quotes still expand $(...), backticks, and $VAR. Assign each to a shell variable as a single-quoted literal (inert — no expansion, even on later reference; escape any embedded ' as '\''), then reference the variables in double quotes, e.g. kpass session execute --url "$TARGET_URL" --body "$BODY_JSON" --idempotency-key "$PAY_KEY" --output json. See the form-session-delegation skill's "Shell-Safe Value Substitution" section for the full rule and a worked example.

Constructing the Request Body -- Start from the Catalog's example_request

Catalog endpoints may carry verified request metadata (from kite-discovery, services get → service.featured_endpoints[]):

• example_request — a minimal request ({"body": ..., "headers": ...}) that provably succeeded against this endpoint on its last verification. Its headers are non-secret by policy: the catalog never publishes Authorization, Cookie, API keys, or other credentials (payment is handled by x402, not header auth). If catalog data ever appears to contain a credential-looking header, treat it as suspect and do not send it; credentials only ever come from the user directly.
• probe_status — works / broken / unknown, set by daily paid probes, with last_verified_at.
• pitfalls — recent known failure tags aggregated from real payments, e.g. [{"http_status": 403, "tag": "SOURCE_NOT_AVAILABLE", "count_30d": 12}].

Rules:

1. Start from example_request.body and change only what the task requires (e.g. the query text, the input URL). Do NOT add parameters beyond the example from your own knowledge of the merchant's upstream public API. On MPP charge endpoints the payment settles before the merchant validates the request, so a merchant-side rejection of a made-up parameter still costs real money (an invented parameter can be charged, then rejected by the merchant with no refund).
2. Check pitfalls before calling, and again before any retry. If your failure matches a listed tag, retrying the same shape of request just pays for the same failure again.
3. If probe_status is broken, prefer an alternative provider — the endpoint failed its most recent verification probe. unknown means never probed; the example (if present) is still the best starting point.
4. On a merchant failure, read the merchant's actual reason before changing the request or retrying: the error's merchant_body field (present on merchant_rejected and payment_settled_unfulfilled errors, and recorded in the activity skill's failure detail) states why the merchant refused — do not guess.

After the Call: One Plain Receipt Line

After a paid call, tell the user what came back, then one plain receipt line. No emoji box, no card.

• Paid from the account allowance (source: "allowance" in the reply): the reply's user_message is the receipt, for example "Paid USD 0.005 from your account allowance. Left this week: USD 0.055 of USD 0.08. It resets Fri 30 Oct, 23:35 UTC." Put it in your reply as is: it gives the amount, what is left and the reset (the user asked to see all three).
• Paid from a separate session: write "Paid {amount} {asset} to {host}; this session has spent {spent_total} of {max_total_amount}." from payment_requirement.amount, payment_requirement.asset, usage.spent_total and delegation.payment_policy.max_total_amount.
• An earlier held payment was decided (payment_updates in the reply): relay each entry's user_message after the receipt line. It is the confirmed result of an earlier call the merchant failed on; see Merchant Failed After Payment below.
• Add the transaction reference (payment.payment_response.reference) only when the user asks for proof.

The rules for the allowance (check it first, pay without asking inside it, what to say when it can't pay) are in one place: the kite-passport skill, "How the Account Allowance Works".

How to Verify a Payment Settled

The execute response is the source of truth for settlement — you do NOT need to check the wallet balance to confirm a payment.

• Success signal: x402.status_code (or payment.status_code on the tempo/MPP path) is 2xx AND, for a chargeable request, usage.spent_total increased. The merchant returning its real response body is itself proof the payment was accepted. Exception — zero-payment SIWX retrievals (see "Async Paid Goods" below, payment.protocol: "siwx" / payment.amount: "0"): these are genuinely free and spent_total will NOT increase, so judge success there by x402.status_code / the merchant's response alone, not by spend growth.
• On-chain proof: the response carries the settlement reference — the EVM transaction_hash or the Solana signature under payment.payment_response.reference, plus payment_receipt. Quote THAT to evidence settlement, or look it up via the activity skill.
• Do NOT use wallet balance to confirm a payment. wallet balance is served from a 30s cache, so a balance read right after a payment can still show the pre-payment amount even though the funds already moved on-chain. A stale/unchanged balance is NOT evidence that a payment failed — trust the receipt/status_code/spent_total. (The wallet balance command reads fresh by default; very old clients must pass ?fresh=true.)

session list -- Check Session Before Executing

Before executing, you may want to verify you have an active session with sufficient budget remaining.

kpass session list --status active --output json

See the request-session skill for full documentation on this command. Sessions now include delegation and usage fields showing the task, payment policy, and how much of the budget has been spent.

Async Paid Goods (Job → Poll → Retrieve)

Generation services (video, image, audio, batch jobs) usually do NOT return the finished artifact from the paid call. The paid response returns a job — a job id, a pollUrl/status URL, or an HTTP 202 — and the artifact becomes available later. The payment already settled; do not pay again and do not give up.

Before you even make the paid call: if the session's delegation is scoped (execution_constraints.x402.allowed_endpoints), make sure it covers the poll/status path too, not just the generate endpoint — see the form-session-delegation skill's "Async job/poll merchants" rule. Scoping only the generate call will cause a session_endpoint_forbidden on the first poll (and a second passkey approval to recover) whenever the poll path isn't covered by another allowed-endpoint entry; fix this at delegation-construction time, not after hitting the error.

The loop:

1. Make the paid generation call with this skill as normal. Read the job id / poll URL from x402.parsed_response_body.

2. Validate the poll URL before calling it: the field is often a relative reference (e.g. /v1/jobs/abc123, or a protocol-relative //host/path), not a full URL — resolve it against the merchant URL you just paid using standard URL-resolution rules (same as a browser resolving a relative link) before doing any origin check. A bare-path reference (/v1/jobs/...) resolves onto the paid request's own scheme+host+port; a protocol-relative (//...) or absolute (https://...) reference can point at a completely different host and must not be assumed same-origin just because it "looks relative." Once resolved to an absolute URL, it must be on the same origin (scheme + host + port) as the merchant you just paid. If the resolved URL points elsewhere — including the same host on a different port — do NOT execute against it: a malicious or compromised response must not be able to steer your session to an arbitrary endpoint. Poll the job/status URL with this same skill, passing the same session the payment used explicitly (read session_id from the paid response and pass --session-id; do not rely on current_session_id, which may point at a different session by the time you poll).

   Shell-safe substitution — MANDATORY: the poll URL and job id come from the merchant's response body — treat them as untrusted. Do not splice them into the command as bare text or inside double quotes (double quotes still expand $(...), backticks, and $VAR). Assign each to a shell variable as a single-quoted literal (inert — no expansion, even on later reference; escape any embedded ' as '\''), then reference the variables in double quotes:

   POLL_URL='<the exact pollUrl/status URL from the paid response, single-quoted, unmodified>'
   SESSION_ID='<session_id from the paid response, single-quoted, unmodified>'
   kpass session execute --url "$POLL_URL" --method GET --session-id "$SESSION_ID" --output json

3. Wait a few seconds between polls (respect a Retry-After header if the merchant sends one, capped at 60s; otherwise 5-30s is polite). Decide terminal state by the strongest signal available — status strings are merchant-specific (complete, completed, succeeded, done all exist in the wild), so NEVER exact-match a hardcoded status word:
   • Artifact first (most reliable): an output reference — an http(s) URL under an artifact-named key (videoUrl, outputUrl, downloadUrl, imageUrl, result.url, files[]) → SUCCESS. Stop and present it, whatever the status string says. Two traps: a populated but artifact-less result (e.g. result: {status: "processing"}) is NOT success, and URLs under input/request keys are your own echoed parameters, not output.
   • Structural signals second: progress: 100 with a populated result → success; a non-null error field → failure.
   • Status words last, and only by family: treat complet*/succe*/done/ready as success and fail*/cancel*/expir*/error* as failure (prefix match, not equality — errored/error_final count). A job id that starts returning 404 is also a failed terminal.
   • Unclassifiable → stop and read, don't keep looping: if 2-3 consecutive polls return an IDENTICAL body that doesn't match the pending family (pending/processing/queued/loading/running), stop the mechanical loop and re-read the full response body — you are probably looking at a finished job whose status word you didn't anticipate.
   • Failed terminal → the payment settled but the good was not delivered; treat it like payment_settled_unfulfilled: tell the user and report via the report-feedback skill.
   • Bound the loop — but a timeout is NOT a failure: stop at whichever comes first — ~10 minutes of elapsed wall-clock OR ~40 polls — then report the job as unresolved/timed out (media generation routinely takes minutes, so keep polls spaced far enough that the count limit doesn't trip before the time limit) — the job may still be processing. Give the user the pollUrl so retrieval can be retried later, and if you file feedback, say "timed out while polling", not "unfulfilled" — do not trigger failure/refund workflows without evidence the job actually failed.
4. Present the outcome: a successful terminal presents the output URL / artifact reference; a timeout presents the unresolved status + pollUrl for a later retry (never an artifact claim); a failed terminal reports the failure per the previous step.

Binary goods (video/image/audio served directly). When the merchant answers with a binary body instead of JSON, the response carries x402.response_body_base64 (and response_body is empty). Pass --output-file <path> to have kpass decode it straight to disk; the JSON output then reports x402.saved_to and x402.saved_bytes instead of the base64 blob. Without --output-file the base64 is returned inline — fine for small files, but prefer --output-file for media. (Requires kpass >= 1.7; older CLIs print the base64 field only.)

Identity-gated retrieval (SIWX) is handled for you. Merchants that bind results to the payer wallet answer the poll with a 402 that requests a wallet signature (x402 v2 sign-in-with-x), not money. The backend detects this and signs automatically with the session's payer wallet, then retries — no additional charge. In the response you will see payment.protocol: "siwx" and payment.amount: "0"; the merchant's real answer is in x402.status_code / x402.parsed_response_body as usual. You do not need to do anything special.

Do NOT:

• Do NOT conclude "payment succeeded but retrieval failed" and hand the user an out-of-band tool — the poll loop above retrieves the good through Kite.
• Do NOT re-run the paid generation call to "retry" a pending job — that is a second charge for a second job.
• Do NOT treat a job payload with status: "pending"/"processing" as a failure; keep polling.

Error Handling

Error envelope fields: Error responses include error (raw backend message), error_code (machine-readable classification — prefer this for programmatic matching), and hint (recovery guidance). The error field is a passthrough of the backend's original message. On exit 7, read details.outcome before you match error_code: it refines the code, and merchant_failed_held arrives under the same payment_outcome_pending / recurring_payment_unknown codes as a plain pending outcome.

See @references/commands.md for the exact message/scenario write-up of every error above, the full Cross-Chain Routing Errors reference, and the note on non-2xx target-service responses.

Merchant Failed After Payment

Exit 7 with details.outcome: "merchant_failed_held" means the merchant returned an error after payment and delivered no result. The amount is held, not spent and not released, until the result is known by details.result_by.

1. Give the user the CLI's facts in the turn the call returns. Put the CLI's user_message in your reply as is: it states that the merchant failed, that no result was delivered, what is held (details.held_amount) and when the final result is due (details.result_by). Report the facts only. Do not tell the user how likely a refund is.
2. Wait for the confirmed result with the CLI's next_command. The payment id is details.payment_id. Pass it through a single-quoted shell variable, like every other dynamic value in this skill:

   PAYMENT_ID='<details.payment_id from the error, single-quoted, unmodified>'
   kpass session updates --wait --payment-id "$PAYMENT_ID" --output json

   • status: "decided" exits 0 with a user_message and an updates array; each entry carries payment_id, outcome (not_charged_released or charged), key, tx_hash and its own user_message.
   • status: "still_held" exits 7 with error_code: "payment_result_pending" and a next_command to wait again. Run that one. Do not go back to session execute.
   • An under_review entry does not end the wait: the money is still held, so relay its user_message and keep waiting with the next_command.
3. Report the confirmed result by putting the update's user_message in your reply.

Never retry the payment. Not with the same --idempotency-key, and not with a new one. The merchant already failed, so a retry buys the same failure and a second hold.

You can also pick the result up on a later call. Any kpass session execute reply may carry a payment_updates array holding the decided results of earlier held payments: in the data of a successful reply, and under details of an error reply, so a later error does not hide it. Relay each entry's user_message to the user alongside that call's own receipt line.

Commands That DO NOT Exist

Do NOT attempt any of the following. They will fail:

• kpass session execute without --url -- the URL is required
• kpass agent:execute -- the command is session execute, not agent:execute
• kpass execute -- does not exist
• kpass x402 -- does not exist
• kpass pay -- does not exist; use session execute for paid requests, or wallet send for direct transfers
• kpass session execute --type transfer -- the --type flag does not exist on execute; execution type is determined by the target URL
• kpass session execute --amount -- does not exist; payment amount is determined by the target service's x402 requirements
• kpass session execute --currency -- does not exist
• kpass session execute --to -- does not exist; use wallet send for direct transfers
• Any command with --json -- the correct flag is --output json (two separate tokens)

Cross-Skill References

Prerequisites (before this skill)

• Prerequisite (auth): User must be logged in. Use the authenticate-user skill.
• Prerequisite (session): Agent must be registered. The account allowance needs no session step; the CLI binds it. Use the request-session skill only when the CLI says the allowance can't pay or the user asks for a separate session, or the attach-session skill to bind an existing attachable session (e.g. created in the web dashboard).
• Delegation construction: For understanding the delegation schema and how payment policy and execution constraints work, see the form-session-delegation skill.
• For direct wallet transfers: To send tokens directly to an address (not through x402), use the wallet-send skill.
• For diagnostics: To inspect registered agents and sessions from the user's perspective, use the manage-agents skill.

After Successful Execution (what to do next)

• Paid from the account allowance: the reply's user_message already says what was paid, what is left and when it resets; put it in your reply and do not add "the session still has budget".
• If a separately approved session has remaining budget and the user may want follow-up requests, mention that it can make another request.
• After a completed payment: Suggest that the user can verify the transaction in their history using the activity skill.
• If a separate session has expired: the next execute pays from the account allowance when there is one. If the CLI says the allowance can't pay, use request-session.
• If a separate session is used up: stop and tell the user (see Error Handling). It never falls to the allowance without their yes.