playbooks

home / skills / bankrbot / claude-plugins / sdk-job-management

sdk-job-management skill

/x402-sdk-dev/skills/sdk-job-management

This skill helps you manage asynchronous jobs with submit, poll, cancel, and batch options for robust SDK interactions.

npx playbooks add skill bankrbot/claude-plugins --skill sdk-job-management

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.8 KB
---
name: Bankr x402 SDK - Job Management
description: This skill should be used when the user asks about "job status", "check if request completed", "cancel request", "why is my request taking so long", "poll for result", "batch requests", "retry failed request", "request timeout", "async operations", "job lifecycle", "manual polling", or needs advanced control over SDK async operations, manual job polling, batch processing, retry logic, or job cancellation.
version: 1.1.0
---

# SDK Job Management

Manage asynchronous jobs: submit, poll, check status, cancel, and batch operations.

## SDK Methods

| Method | Description | Use Case |
|--------|-------------|----------|
| `promptAndWait()` | Submit and wait for result | **Recommended** for most cases |
| `prompt()` | Submit, return immediately | Background processing |
| `pollJob()` | Poll until job completes | Manual job tracking |
| `getJobStatus()` | Check status once | Custom polling logic |
| `cancelJob()` | Cancel pending/processing job | Stop unwanted jobs |

## Job Lifecycle

```
pending → processing → completed
                    ↘ failed
                    ↘ cancelled
```

| State | Cancellable | Description |
|-------|-------------|-------------|
| pending | Yes | Awaiting processing |
| processing | Yes | Actively processing |
| completed | No | Finished successfully |
| failed | No | Encountered error |
| cancelled | No | Cancelled by user |

## Usage Examples

### Recommended: promptAndWait

```typescript
const result = await client.promptAndWait({
  prompt: "Swap 0.1 ETH to USDC",
  timeout: 60000,
});

if (result.status === "completed") {
  console.log(result.response);
}
```

### Manual Job Control

```typescript
// Submit without waiting
const { jobId } = await client.prompt({ prompt: "What are trending tokens?" });

// Check status later
const status = await client.getJobStatus(jobId);

// Or poll until complete
const result = await client.pollJob({ jobId, timeout: 60000 });
```

### Cancel Job

```typescript
const { jobId } = await client.prompt({ prompt: "..." });
await client.cancelJob(jobId);
```

### Batch Processing

```typescript
const prompts = ["Price of ETH", "Price of BTC", "Price of SOL"];

// Submit all in parallel
const jobs = await Promise.all(
  prompts.map(prompt => client.prompt({ prompt }))
);

// Wait for all to complete
const results = await Promise.all(
  jobs.map(job => client.pollJob({ jobId: job.jobId }))
);
```

## Timing Guidelines

| Operation | Typical Time | Recommended Timeout |
|-----------|--------------|---------------------|
| Price queries | 2-5s | 15s |
| Balance checks | 2-5s | 15s |
| Token swaps | 5-15s | 60s |
| Cross-chain bridges | 10-30s | 120s |
| NFT operations | 5-15s | 60s |

## Related Skills

- **sdk-wallet-operations**: Client setup and configuration
- **sdk-capabilities**: Full list of supported operations

Overview

This skill explains how to manage asynchronous jobs in the Bankr x402 JavaScript SDK for multi-chain DeFi tasks. It covers submitting jobs, polling, checking status, cancelling, batching, and recommended timeouts so you can handle long-running or background operations reliably.

How this skill works

The SDK exposes both blocking and non-blocking methods: promptAndWait() submits and waits for completion, while prompt() returns immediately with a jobId for manual tracking. Use getJobStatus() for a single status check, pollJob() to wait until completion with a timeout, and cancelJob() to stop pending or processing jobs. Jobs follow a lifecycle: pending → processing → completed, failed, or cancelled.

When to use it

  • You need to check job status or poll for results after submitting an async request.
  • Requests may take longer than a single HTTP call (swaps, bridges, or complex queries).
  • You want to submit work in background and retrieve results later (batch processing).
  • You need ability to cancel pending or currently processing work.
  • You want custom retry and timeout strategies for unstable operations.

Best practices

  • Prefer promptAndWait() for simple flows where waiting is acceptable; it handles polling internally.
  • Use prompt() + pollJob() for manual control, batching, or when you must offload work to background processes.
  • Set timeouts based on operation type (e.g., 15s for price queries, 60–120s for cross-chain operations).
  • Implement exponential backoff and a capped retry count for transient failures instead of tight tight loops.
  • Always check job status before retrying or cancelling to avoid duplicate side effects.

Example use cases

  • Submit a token swap and wait up to 60s for completion using promptAndWait().
  • Start multiple price queries with prompt(), then poll all jobIds in parallel and aggregate results.
  • Submit a balance aggregation job and periodically check status with getJobStatus() from a dashboard.
  • Cancel a pending cross-chain bridge request if the user changes their mind before processing starts.
  • Retry failed NFT minting requests with controlled backoff and maximum retry attempts.

FAQ

When should I use pollJob() vs promptAndWait()?

Use promptAndWait() for simple synchronous-style flows. Use pollJob() when you need manual control, advanced retry logic, or batching across many jobs.

Can I cancel a job after it starts processing?

Yes. Jobs in pending or processing states are cancellable; once completed, failed, or cancelled they cannot be changed.

How do I choose timeouts for different operations?

Follow recommended timing guidelines: short queries 15s, swaps and NFT ops 60s, cross-chain bridges 120s. Add headroom for network variability and rate limits.