huggingbay-xyz X402 API
The X402 API from huggingbay-xyz — 2 operation(s) for x402.
The X402 API from huggingbay-xyz — 2 operation(s) for x402.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/huggingbay-xyz:huggingbay-xyz-x402-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Bay Run X402 API
version: 2.0.0
servers:
- url: https://run.huggingbay.xyz
tags:
- name: X402
paths:
/x402/chat/completions:
x-bay-run-visibility: internal/advanced
post:
summary: X402 Payable
description: Tokenless, pay-per-call twin of /v1/chat/completions.
operationId: x402_payable_x402_chat_completions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'402':
description: Payment Required; inspect the response payment challenge or Link header.
'503':
description: Payment settlement or durable billing is unavailable; retry later.
headers:
Retry-After:
description: Seconds before the client should retry.
schema:
type: integer
minimum: 1
security: []
x-bay-run-visibility: internal/advanced
x-payment-info:
availability: configured
configuration_ready: true
settlement_ready: true
settlement_observed: false
settlement_evidence:
observed: false
basis: configuration_only
configuration_is_not_settlement_evidence: true
blocker: null
buyerRecipeAvailable: true
buyerRecipeUnavailableReasons: []
offers:
- intent: charge
method: x402
amount: '5000'
currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
description: One legacy chat completion paid in USDC on eip155:8453; the runtime 402 challenge is authoritative.
runtimeDiscovery: https://run.huggingbay.xyz/.well-known/x402
buyerRecipe: https://run.huggingbay.xyz/.well-known/x402/recipes/base-mainnet-usdc
tags:
- X402
/x402/tasks/run:
x-bay-run-visibility: internal/advanced
post:
summary: X402 Task Payable
description: 'Tokenless Base-mainnet USDC twin of the focused run_task contract.
A bearer may be supplied to execute a quote created under an OAuth/developer
principal. Without one, callers use quote-and-run with a complete task spec;
the facilitator-verified payer and accepted network become the stable
tokenless execution principal. Billing still uses its payment fingerprint
for payment receipt and replay accounting.'
operationId: x402_task_payable_x402_tasks_run_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/X402TaskRunRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskExecutionResponse'
'402':
description: Payment Required; inspect the response payment challenge or Link header.
'409':
description: The quote, profile, receipt, or idempotency state conflicts with this request.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskErrorResponse'
'422':
description: The task constraints or hard price ceiling cannot be satisfied.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskErrorResponse'
'503':
description: Payment settlement or durable billing is unavailable; retry later.
headers:
Retry-After:
description: Seconds before the client should retry.
schema:
type: integer
minimum: 1
'504':
description: The execution exceeded the caller's hard latency requirement.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskErrorResponse'
security: []
x-bay-run-visibility: internal/advanced
x-payment-info:
availability: configured
configuration_ready: true
settlement_ready: true
settlement_observed: false
settlement_evidence:
observed: false
basis: configuration_only
configuration_is_not_settlement_evidence: true
blocker: null
buyerRecipeAvailable: true
buyerRecipeUnavailableReasons: []
offers:
- intent: charge
method: x402
amount: '5000'
currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
description: One focused task execution paid in USDC on eip155:8453; the runtime 402 challenge and caller hard price ceiling are authoritative.
runtimeDiscovery: https://run.huggingbay.xyz/.well-known/x402
buyerRecipe: https://run.huggingbay.xyz/.well-known/x402/recipes/task-run-base-mainnet-usdc
x-bay-run-idempotency:
required: true
location: body
field: idempotency_key
x-bay-run-x402-task-contract:
authorization:
model: exact_one_call_wallet_payment
tokenless: true
oneCall: true
completeTaskRequired: true
storedQuoteAllowed: false
storedProfileAllowed: false
savedProfileAllowed: false
ownerApprovalAllowed: false
accountCumulativePolicyApplied: false
walletCumulativePolicy: The buyer or agent harness must enforce wallet-level hourly, daily, monthly, and other cumulative approval limits.
accountManagedAlternative: Use an authenticated owner route when server-side identity, stored state, or account-managed spending policy is required.
tokenlessDataBoundary:
retention:
- none
- execution_metadata
external_apis_allowed: false
saved_profiles: false
stored_quotes: false
account_cumulative_policy: false
hardMaxPrice:
field: max_price_usd
required: true
hard: true
serverEnforced: true
actualPriceField: actual_price_usd
paymentCeiling: payment.maxAmountAtomic
meaning: The server rejects a task when its actual price exceeds the caller's declared ceiling.
retry:
challengeStatus: 402
challengeHeader: PAYMENT-REQUIRED
signedRetryHeader: PAYMENT-SIGNATURE
preserveRequestBody: true
preserveIdempotencyKey: true
newPaymentAuthorizationRequired: true
transient:
statuses:
- 409
- 503
header: Retry-After
honorBeforeRetry: true
onlyWhenErrorRetriable: true
doNotBlindlyRetry: Do not submit another payment authorization for an ambiguous result until the payment and execution state is known.
receipts:
payment:
settlementHeader: PAYMENT-RESPONSE
serviceHeader: x-bay-run-payment-receipt
meaning: Facilitator settlement and Bay Run billing evidence for the exact payment.
execution:
responseField: execution_receipt
statusField: status
pendingStatus: pending_settlement
issuedAfter: durable settlement finalization
verificationPath: /v1/task/verify
responseHeaders:
executionId: x-bay-run-execution-id
actualPrice: x-bay-run-actual-price-usd
authorizationModel: x-bay-run-authorization-model
meaning: Bound task execution evidence for the execution, price, hashes, policy, and route claims that are stored.
limitations:
- PAYMENT-RESPONSE proves the x402 payment settlement response, not universal task safety.
- x-bay-run-payment-receipt identifies Bay Run billing evidence; it is distinct from the task execution receipt.
- An execution receipt can be pending or absent until durable settlement finalization completes.
- HMAC task/payment receipts are a MAC, not a proof; the HMAC receipt does not prove answer truth, quality, or cryptographic attestation of the execution environment. A separate Ed25519 result proof can bind the served Hugging Bay weight hash.
suitability:
decisionType: task_specific_not_universal
universalSafetyClaim: false
ownerMustDecide: true
receiptDoesNotProve:
- answer truth
- task quality
- regulatory or contractual suitability
- model-weight identity when the receipt lacks its manifest binding
- cryptographic attestation of the execution environment
tags:
- X402
components:
schemas:
TaskExecutionResponse:
properties:
schema:
type: string
title: Schema
default: bay-run.task-execution.v1
execution_id:
anyOf:
- type: string
- type: 'null'
title: Execution Id
quote_id:
anyOf:
- type: string
- type: 'null'
title: Quote Id
task_profile_id:
anyOf:
- type: string
- type: 'null'
title: Task Profile Id
status:
anyOf:
- type: string
- type: 'null'
title: Status
output:
title: Output
actual_price_usd:
anyOf:
- type: string
- type: 'null'
title: Actual Price Usd
actual_latency_ms:
anyOf:
- type: integer
- type: 'null'
title: Actual Latency Ms
provider:
anyOf:
- type: string
- type: 'null'
title: Provider
model:
anyOf:
- type: string
- type: 'null'
title: Model
model_version:
anyOf:
- type: string
- type: 'null'
title: Model Version
route:
additionalProperties: true
type: object
title: Route
fallback_route:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Fallback Route
quality:
title: Quality
payment_status:
anyOf:
- type: string
- type: 'null'
title: Payment Status
payment_receipt:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Payment Receipt
data_retention:
anyOf:
- type: string
enum:
- none
- execution_metadata
- task_profile
- type: 'null'
title: Data Retention
input_hash:
anyOf:
- type: string
- type: 'null'
title: Input Hash
replayed:
anyOf:
- type: boolean
- type: 'null'
title: Replayed
execution_receipt:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Execution Receipt
output_retained:
anyOf:
- type: boolean
- type: 'null'
title: Output Retained
learning:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Learning
next_call:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Next Call
description: Machine-readable verification call for the returned execution, when available.
durable_free_key:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Durable Free Key
description: Email-free durable-key offer with its published daily task quota.
additionalProperties: true
type: object
required:
- schema
- execution_id
- quote_id
- status
- output
- actual_price_usd
- actual_latency_ms
- payment_status
- replayed
title: TaskExecutionResponse
description: Explicit response contract for an execution and its receipt envelope.
ChatFunctionTool:
properties:
type:
type: string
const: function
title: Type
function:
$ref: '#/components/schemas/ChatFunctionDefinition'
additionalProperties: false
type: object
required:
- type
- function
title: ChatFunctionTool
ChatNamedToolChoice:
properties:
type:
type: string
const: function
title: Type
function:
$ref: '#/components/schemas/ChatNamedFunctionChoice'
additionalProperties: false
type: object
required:
- type
- function
title: ChatNamedToolChoice
TaskErrorDetail:
properties:
code:
type: string
title: Code
reason:
type: string
title: Reason
retriable:
type: boolean
title: Retriable
default: false
recommended_action:
anyOf:
- type: string
- type: 'null'
title: Recommended Action
details:
anyOf:
- additionalProperties: true
type: object
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Details
next_call:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Next Call
description: Machine-readable recovery call, when one is available.
additionalProperties: true
type: object
required:
- code
- reason
title: TaskErrorDetail
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
TaskLearningPolicy:
properties:
enabled:
type: boolean
title: Enabled
default: false
auto_record_platform_outcomes:
type: boolean
title: Auto Record Platform Outcomes
default: false
route_change_mode:
type: string
enum:
- propose
- apply
title: Route Change Mode
default: propose
min_observations:
type: integer
maximum: 1000.0
minimum: 1.0
title: Min Observations
default: 10
min_failures:
type: integer
maximum: 100.0
minimum: 1.0
title: Min Failures
default: 3
additionalProperties: false
type: object
title: TaskLearningPolicy
description: Owner-controlled, bounded policy for automatic operational learning.
ChatNamedFunctionChoice:
properties:
name:
type: string
maxLength: 64
minLength: 1
pattern: ^[A-Za-z0-9_-]+$
title: Name
additionalProperties: false
type: object
required:
- name
title: ChatNamedFunctionChoice
MemoryInjectionOptions:
properties:
namespace:
type: string
maxLength: 256
minLength: 1
title: Namespace
default: default
query:
anyOf:
- type: string
maxLength: 256
minLength: 1
- type: 'null'
title: Query
max_items:
type: integer
maximum: 50.0
minimum: 1.0
title: Max Items
default: 8
max_bytes:
type: integer
maximum: 1048576.0
minimum: 69632.0
title: Max Bytes
default: 69632
max_tokens:
type: integer
maximum: 4096.0
minimum: 1.0
title: Max Tokens
description: Conservative UTF-8-byte token-equivalent cap for injected memory.
default: 4096
additionalProperties: false
type: object
title: MemoryInjectionOptions
description: Opt-in, bounded memory retrieval for supported inference tools.
ChatCompletionsRequest:
properties:
model:
type: string
title: Model
messages:
items:
$ref: '#/components/schemas/ChatMessage'
type: array
title: Messages
max_tokens:
type: integer
title: Max Tokens
default: 512
max_completion_tokens:
anyOf:
- type: integer
- type: 'null'
title: Max Completion Tokens
temperature:
type: number
title: Temperature
default: 0.0
response_format:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Response Format
stop:
anyOf:
- type: string
- items:
type: string
type: array
- type: 'null'
title: Stop
stream:
type: boolean
title: Stream
default: false
stream_options:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Stream Options
task_hint:
anyOf:
- type: string
- type: 'null'
title: Task Hint
interactive_deadline_ms:
anyOf:
- type: integer
maximum: 120000.0
minimum: 0.0
- type: 'null'
title: Interactive Deadline Ms
description: Optional caller deadline in milliseconds. Basic structured work uses the CPU fast lane; advanced chat uses Qwen3 and returns no_specialists when that lane is unavailable.
prefer_async:
type: boolean
title: Prefer Async
default: false
prefer_warm:
type: boolean
title: Prefer Warm
default: true
namespace:
anyOf:
- type: string
maxLength: 256
- type: 'null'
title: Namespace
description: Private learned-routing namespace used by model='auto'.
routing_mode:
type: string
enum:
- default
- strict
title: Routing Mode
description: default permits the bounded same-kind fallback; strict requires a live private proof.
default: default
tools:
anyOf:
- items:
$ref: '#/components/schemas/ChatFunctionTool'
type: array
maxItems: 128
minItems: 1
- type: 'null'
title: Tools
tool_choice:
anyOf:
- type: string
enum:
- none
- auto
- required
- $ref: '#/components/schemas/ChatNamedToolChoice'
- type: 'null'
title: Tool Choice
description: Honored end-to-end for unary requests. With stream=true, a demanded named or required choice runs through the same model-backed unary tool contract and its validated result is re-emitted as SSE; no tool-call chunk is emitted unless the model produced that call. Missing or invalid demanded calls fail with a typed non-2xx response before SSE starts. Undemanded tools are ignored while ordinary assistant text streams, declared by x-bay-run-tools-ignored.
parallel_tool_calls:
anyOf:
- type: boolean
- type: 'null'
title: Parallel Tool Calls
functions:
anyOf:
- items:
$ref: '#/components/schemas/ChatFunctionDefinition'
type: array
maxItems: 128
minItems: 1
- type: 'null'
title: Functions
function_call:
anyOf:
- type: string
enum:
- none
- auto
- $ref: '#/components/schemas/ChatNamedFunctionChoice'
- type: 'null'
title: Function Call
memory:
anyOf:
- $ref: '#/components/schemas/MemoryInjectionOptions'
- type: 'null'
automatic_memory:
anyOf:
- $ref: '#/components/schemas/MemoryAutomaticOptions'
- type: 'null'
type: object
required:
- model
- messages
title: ChatCompletionsRequest
ChatMessageFunctionCall:
properties:
name:
type: string
title: Name
arguments:
type: string
title: Arguments
additionalProperties: false
type: object
required:
- name
- arguments
title: ChatMessageFunctionCall
MemoryAutomaticOptions:
properties:
namespace:
type: string
maxLength: 256
minLength: 1
title: Namespace
default: default
key:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Key
ttl:
anyOf:
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Ttl
description: Expiry in seconds. Null uses the server's bounded automatic-memory default; automatic memory cannot create an indefinite entry.
default: 2592000
importance:
type: integer
maximum: 100.0
minimum: 0.0
title: Importance
default: 0
max_bytes:
type: integer
maximum: 16384.0
minimum: 256.0
title: Max Bytes
default: 16384
semantic:
type: boolean
title: Semantic
default: true
additionalProperties: false
type: object
title: MemoryAutomaticOptions
description: Opt-in bounded storage policy for a supported inference result.
X402TaskRunRequest:
oneOf:
- required:
- quote_id
- required:
- profile_id
- required:
- task
properties:
quote_id:
anyOf:
- type: string
maxLength: 96
minLength: 8
- type: 'null'
title: Quote Id
task:
anyOf:
- $ref: '#/components/schemas/TaskSpecification'
- type: 'null'
profile_id:
anyOf:
- type: string
maxLength: 96
minLength: 8
- type: 'null'
title: Profile Id
reevaluate_profile:
type: boolean
title: Reevaluate Profile
default: false
input:
title: Input
max_price_usd:
anyOf:
- type: number
- type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
title: Max Price Usd
idempotency_key:
type: string
maxLength: 200
minLength: 8
title: Idempotency Key
owner_approval_id:
anyOf:
- type: string
maxLength: 96
minLength: 8
- type: 'null'
title: Owner Approval Id
payment_mode:
type: string
const: x402
title: Payment Mode
default: x402
save_profile:
type: boolean
title: Save Profile
default: false
profile_name:
anyOf:
- type: string
maxLength: 120
minLength: 1
- type: 'null'
title: Profile Name
learning:
anyOf:
- $ref: '#/components/schemas/TaskLearningPolicy'
- type: 'null'
additionalProperties: false
type: object
required:
- input
- max_price_usd
- idempotency_key
title: X402TaskRunRequest
description: Paid route request; the x402 middleware remains the authority for payment.
ChatMessage:
properties:
role:
type: string
title: Role
content:
anyOf:
- type: string
- type: 'null'
title: Content
name:
anyOf:
- type: string
- type: 'null'
title: Name
tool_call_id:
anyOf:
- type: string
- type: 'null'
title: Tool Call Id
tool_calls:
anyOf:
- items:
$ref: '#/components/schemas/ChatMessageToolCall'
type: array
- type: 'null'
title: Tool Calls
function_call:
anyOf:
- $ref: '#/components/schemas/ChatMessageFunctionCall'
- type: 'null'
type: object
required:
- role
title: ChatMessage
TaskDataPolicy:
properties:
open_source_required:
type: boolean
title: Open Source Required
default: true
external_apis_allowed:
type: boolean
title: External Apis Allowed
default: false
allowed_providers:
items:
type: string
type: array
maxItems: 32
title: Allowed Providers
disallowed_providers:
items:
type: string
type: array
maxItems: 32
title: Disallowed Providers
allowed_regions:
items:
type: string
type: array
maxItems: 16
title: Allowed Regions
retention:
type: string
enum:
- none
- execution_metadata
- task_profile
title: Retention
default: execution_metadata
retention_seconds:
anyOf:
- type: integer
maximum: 31536000.0
minimum: 60.0
- type: 'null'
title: Retention Seconds
use_for_training:
type: boolean
const: false
title: Use For Training
default: false
additionalProperties: false
type: object
title: TaskDataPolicy
ChatMessageToolCall:
properties:
id:
type: string
title: Id
type:
type: string
const: function
title: Type
function:
$ref: '#/components/schemas/ChatMessageFunctionCall'
additionalProperties: false
type: object
required:
- id
- type
- function
title: ChatMessageToolCall
ChatFunctionDefinition:
properties:
name:
type: string
maxLength: 64
minLength: 1
pattern: ^[A-Za-z0-9_-]+$
title: Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
parameters:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Parameters
strict:
anyOf:
- type: boolean
- type: 'null'
title: Strict
additionalProperties: false
type: object
required:
- name
title: ChatFunctionDefinition
TaskSpecification:
properties:
task:
type: string
maxLength: 512
minLength: 3
title: Task
kind:
type: string
enum:
- auto
- classification
- embedding
- rerank
- extraction
title: Kind
default: auto
input_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Input Schema
output_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Output Schema
examples:
items:
additionalProperties: true
type: object
type: array
maxItems: 20
title: Examples
constraints:
$ref: '#/components/schemas/TaskConstraints'
data_policy:
$ref: '#/components/schemas/TaskDataPolicy'
frequency:
type: string
enum:
- one_time
- recurring
title: Frequency
default: one_time
environment:
type: string
enum:
- development
- production
title: Environment
default: production
route_switch_policy:
type: string
enum:
- disabled
- approval_required
title: Route Switch Policy
default: approval_required
additionalProperties: false
type: object
required:
- task
title: TaskSpecification
TaskConstraints:
properties:
minimum_quality:
anyOf:
- type: number
maximum: 1.0
minimum: 0.0
- type: 'null'
title: Minimum Quality
max_latency_ms:
anyOf:
- type: integer
maximum: 300000.0
minimum: 1.0
- type: 'null'
title: Max Latency Ms
max_price_usd:
anyOf:
- type: number
- type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
title: Max Price Usd
default: '0.01'
additionalProperties: false
type: object
title: TaskConstraints
TaskErrorResponse:
properties:
error:
$ref: '#/components/schemas/TaskErrorDetail'
additionalProperties: true
type: object
required:
- error
title: TaskErrorResponse
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: OAuth access token, bay_live_ durable free key, or configured bearer
description: Bay Run OAuth access token, email-free revocable bay_live_ demo key, or configured operator/demo bearer.
DeveloperApiKey:
type: http
scheme: bearer
bearerFormat: bayr1.<credential_id>.<one-time-secret>
description: OAuth-owned, revocable developer key. The raw secret is shown only on create/rotate and stored solely as a dedicated-pepper HMAC digest. Owner-management scopes require operator-attested enrollment; public OAuth alone cannot issue them. billing:write controls checkout, policy, and approval. billing:spend is the separate agent-spend authority and must be paired with inference:invoke. Keep OAuth and billing:write keys out of agent harnesses.
OperatorBearer:
type: http
scheme: bearer
description: Platform operator secret accepted only on explicitly documented owner-management operations. It is not an OAuth access token and must never be placed in an agent harness.
x-service-info:
categories:
- compute
- developer-tools
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://artifacts.apis.io/huggingbay-xyz/openapi/huggingbay-xyz-x402-api-openapi.yml