---
title: "Buy a run of a skill runner a seller offers"
method: POST
path: "/v1/skills/{owner}/{name}/run"
tags: ["runs", "skills"]
---

# Buy a run of a skill runner a seller offers

`POST /v1/skills/{owner}/{name}/run`

## Request

- Base URL: `https://api.runx.ai`
- URL: `https://api.runx.ai/v1/skills/{owner}/{name}/run`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Runx-Purchaser-Key`
  - none

A runx account buys with its token, and pays with x402, a payment body, or account_payment: a quote it decided on, paid from its runx balance or one of its payment grants. A buyer with no account names purchaser_key, which owns the purchase; a purchase on a resource held under that key also carries the key's signature.

## Path parameters

- `owner` string, required
- `name` string, required

## Headers

- `Idempotency-Key` string
- `PAYMENT-SIGNATURE` string
- `X-Runx-Purchaser-Signature` string
- `X-Runx-Purchaser-Issued-At` string

## Request body

- RunSkillRequest
  - `runner` string
  - `inputs` object
  - `idempotency_key` string
  - `payment` RunxExecutePaidInvocationRequest
    - `idempotency` object, required
      - `binding_digest` string, required
      - `key` string, required
    - `invocation_id` string, required
    - `payment_ref` object, required
      - `label` string
      - `locator` string
      - `observed_at` string
      - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
      - `provider` string
      - `type` 'thread' | 'comment' | 'event' | 'tracking_item' | 'change_request' | 'repository' | 'signal' | 'run' | 'act' | 'receipt' | 'artifact' | 'verification' | 'harness' | 'host' | 'surface' | 'target' | 'skill_binding' | 'principal' | 'scope_admission' | 'grant' | 'mandate' | 'credential' | 'webhook_delivery' | 'redaction_policy' | 'external_url' | 'connector_instance' | 'connector_operation', required
      - `uri` string, required
    - `settlement_family` string, required
  - `account_payment` union: An account purchase: the quoted invocation its buyer decided on, paid from the account's runx balance or with one of its payment grants.
    - object
      - `invocation_id` string, required
      - `method` 'balance', required
    - object
      - `invocation_id` string, required
      - `method` 'grant', required
      - `grant_id` string, required
  - `version` string: The listing version the buyer priced; a purchase of another is refused.
  - `purchaser_key` string: The Ed25519 key that owns the purchase: it signs the purchase's reads and claims.

## Response `201`

The purchase its buyer reads.

- RunxPurchase
  - `balance_micro` integer
  - `failure` object
    - `code` string, required
    - `message` string, required
  - `holds` object[]
    - `connector` string, required
    - `credential` string, required
    - `expires_at` string, required
    - `target` string, required
    - `value_digest` string, required
  - `invocation` object, required
    - `accepted_settlement_families` string[], required
    - `amount_minor` integer, required
    - `canonicalizer_version` 'runx.receipt.c14n.v1', required
    - `counterparty` object, required
      - `label` string
      - `locator` string
      - `observed_at` string
      - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
      - `provider` string
      - `type` 'thread' | 'comment' | 'event' | 'tracking_item' | 'change_request' | 'repository' | 'signal' | 'run' | 'act' | 'receipt' | 'artifact' | 'verification' | 'harness' | 'host' | 'surface' | 'target' | 'skill_binding' | 'principal' | 'scope_admission' | 'grant' | 'mandate' | 'credential' | 'webhook_delivery' | 'redaction_policy' | 'external_url' | 'connector_instance' | 'connector_operation', required
      - `uri` string, required
    - `created_at` string, required
    - `currency` string, required
    - `execution_ref` object
      - `label` string
      - `locator` string
      - `observed_at` string
      - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
      - `provider` string
      - `type` 'thread' | 'comment' | 'event' | 'tracking_item' | 'change_request' | 'repository' | 'signal' | 'run' | 'act' | 'receipt' | 'artifact' | 'verification' | 'harness' | 'host' | 'surface' | 'target' | 'skill_binding' | 'principal' | 'scope_admission' | 'grant' | 'mandate' | 'credential' | 'webhook_delivery' | 'redaction_policy' | 'external_url' | 'connector_instance' | 'connector_operation', required
      - `uri` string, required
    - `execution_state` 'unstarted' | 'queued' | 'running' | 'waiting_external' | 'cancelling' | 'succeeded' | 'failed' | 'cancelled', required
    - `expires_at` string, required
    - `external_job_ref` object
      - `label` string
      - `locator` string
      - `observed_at` string
      - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
      - `provider` string
      - `type` 'thread' | 'comment' | 'event' | 'tracking_item' | 'change_request' | 'repository' | 'signal' | 'run' | 'act' | 'receipt' | 'artifact' | 'verification' | 'harness' | 'host' | 'surface' | 'target' | 'skill_binding' | 'principal' | 'scope_admission' | 'grant' | 'mandate' | 'credential' | 'webhook_delivery' | 'redaction_policy' | 'external_url' | 'connector_instance' | 'connector_operation', required
      - `uri` string, required
    - `idempotency` object, required
      - `binding_digest` string, required
      - `key` string, required
    - `input_digest` string, required
    - `invocation_id` string, required
    - `offer_revision` object, required
      - `input_schema_digest` string, required
      - `offer_id` string, required
      - `output_schema_digest` string, required
      - `revision` string, required
      - `revision_digest` string, required
    - `outcome_gate` 'open' | 'fulfilment_won' | 'refund_won', required
    - `package_digest` string, required
    - `payment_ref` object
      - `label` string
      - `locator` string
      - `observed_at` string
      - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
      - `provider` string
      - `type` 'thread' | 'comment' | 'event' | 'tracking_item' | 'change_request' | 'repository' | 'signal' | 'run' | 'act' | 'receipt' | 'artifact' | 'verification' | 'harness' | 'host' | 'surface' | 'target' | 'skill_binding' | 'principal' | 'scope_admission' | 'grant' | 'mandate' | 'credential' | 'webhook_delivery' | 'redaction_policy' | 'external_url' | 'connector_instance' | 'connector_operation', required
      - `uri` string, required
    - `payment_state` 'unpaid' | 'settling' | 'settled' | 'refunded', required
    - `principal` object, required
      - `label` string
      - `locator` string
      - `observed_at` string
      - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
      - `provider` string
      - `type` 'principal', required
      - `uri` string, required
    - `purchaser_key` string
    - `settlement_family` string
    - `updated_at` string, required
    - `vendor_ref` object, required
      - `label` string
      - `locator` string
      - `observed_at` string
      - `proof_kind` 'effect_evidence' | 'effect_finality' | 'credential_resolution'
      - `provider` string
      - `type` 'principal', required
      - `uri` string, required
  - `receipt` object
  - `result` unknown

## Other responses

- `400`: Validation error.
- `401`: Unauthorized.
- `402`: Payment challenge or rail-neutral refusal.
- `409`: The runner carries no offer, the quote or version changed, the resource it acts on is not held, or paid admission conflicts.

---

[API](https://skmtc.dev/runx/apis/runx-hosted-api.md) · [All operations](https://skmtc.dev/runx/apis/runx-hosted-api/llms.txt) · [OpenAPI document](https://skmtc.dev/runx/apis/runx-hosted-api/revisions/6c940d8edacc?raw)