# Blockchain IQ market brief for LangChain

A real LangChain JavaScript tool that buys one Blockchain IQ market brief with
x402 v2 and returns the JSON response plus settlement evidence. It uses the
vendor's documented `@x402/fetch` / `@x402/evm` payment flow.

The request is fixed to
`https://www.blockchainiq.co/api/x402/v1/brief`. It accepts exactly **0.01 USDC
(10,000 atomic units) on Base, chain 8453**, paid to an application-configured
recipient. A model cannot supply a URL, wallet key, recipient, network or amount.
This package contains no wallet or API credential. No Blockchain IQ account,
model API key or LLM is needed to invoke the tool.

This is AI-assisted software produced by an AI-operated project under its human
operator. It is an independent integration and is not endorsed by
Blockchain IQ. Published bounty terms describe a conditional reward; this
repository does not establish an available slot, sponsor acceptance or payment.

## Install and test

Use Node.js 22 or later and npm. Install from the pinned lockfile without running
dependency lifecycle scripts:

```sh
npm ci --ignore-scripts --no-audit --no-fund
npm test
node src/cli.js --help
```

The tests use the actual LangChain and x402 packages, synthetic HTTP responses,
public fixture addresses and a mock signer. They do not load a wallet, contact
the API, query an RPC, make a payment or use valid payment signatures. Importing
the package, running tests or showing CLI help does not access the network.

Pinned direct dependencies are `@langchain/core` 1.3.0, `@x402/fetch` 2.28.0,
`@x402/evm` 2.28.0, `viem` 2.57.11 and `zod` 4.6.7. The complete dependency
integrity hashes are in `package-lock.json`.

## Inspect a free quote

This command makes one unsigned GET to the fixed brief endpoint. It checks the
challenge and prints the amount, network, token and proposed payment recipient:

```sh
node src/cli.js --quote
```

It never loads or constructs a wallet signer. Review the returned recipient
against the provider's current official payment terms before configuring a paid
call. A quote is neither a payment nor proof of ownership of the recipient.
Unexpected pricing, tokens, networks, fee fields, authorization extensions or
responses stop the command. Do not change endpoints or identities to work around
a provider refusal.

## Make one real call

Use a dedicated throwaway wallet holding a small amount of native USDC on Base.
The provider documents gasless x402 settlement for the payer. Keep the key in
your local environment or secret manager; do not place it in command arguments,
a repository, a notebook or a tool's model-visible input.

After configuring `AGENT_PRIVATE_KEY` securely in your own environment, invoke
the tool once with the reviewed recipient:

```sh
node src/cli.js --pay --pay-to 0xREPLACE_WITH_REVIEWED_PROVIDER_RECIPIENT
```

The placeholder intentionally is not a valid address. The CLI reads the key
only after it accepts the payment challenge. It signs one EIP-3009 authorization
and sends one paid retry. It never sends a third request, signs a second payment
or retries a failed paid call automatically.

Successful output is JSON with:

```json
{
  "response": {
    "source": "Blockchain IQ",
    "disclaimer": "...",
    "terms": "https://www.blockchainiq.co/terms",
    "data": { "asOf": "...", "coins": [], "events": [], "flags": [] }
  },
  "settlement": {
    "transaction": "0x...",
    "payer": "0x...",
    "network": "eip155:8453"
  }
}
```

The tool decodes `PAYMENT-RESPONSE` and checks success, transaction hash shape,
network and payer. That header is provider-reported settlement evidence. Verify
the actual transaction separately before treating a payment as confirmed; this
package makes no independent chain-finality claim. Neither signatures nor the
private key are included in the output.

If a paid request times out, fails or returns malformed data, the error includes
`paymentMayHaveCommitted: true`. Stop and check the transaction/provider status
separately. Starting another process would create a new attempt; the package has
no persistent cross-process journal and does not authorize that retry.

## Use the LangChain tool directly

```js
import { privateKeyToAccount } from 'viem/accounts';
import { createBlockchainIqBriefTool } from './src/index.js';

const briefTool = createBlockchainIqBriefTool({
  expectedPayTo: process.env.BLOCKCHAINIQ_PAY_TO,
  signerFactory: () => privateKeyToAccount(process.env.AGENT_PRIVATE_KEY),
});

const result = JSON.parse(await briefTool.invoke({}));
console.log(result.response.data);
console.log(result.settlement);
```

Wallet and recipient configuration belong to the surrounding application. The
tool's input schema is an empty strict object. Each tool instance is single-use,
including after an error; a second or concurrent invocation cannot pay again.
Creating another instance is an explicit new paid-call decision for your
application to budget. `fetchImpl` and `signerFactory` injection are available
for offline tests and application integration, not model-selected inputs.

The market brief returns prices and recent moves for major coins, upcoming
events and risk flags. It is market data and analysis, not investment advice.
Provider terms apply to the data and API. The MIT license covers this integration
code, not ownership of the provider's content or a right to redistribute it.

## Bounty review checklist

The [official bounty announcement](https://www.blockchainiq.co/blog/x402-build-bounties)
asks for a public repository and one real paid call through the claimed framework
to `brief` or `event-risk`. This repository selects **LangChain** and `brief`.

For a sponsor review in a clean isolated environment:

1. Review the code, dependency lock and tests; run the offline commands above.
2. Use the sponsor's own throwaway wallet and review a current unsigned quote.
3. Invoke the actual LangChain tool once with that recipient and exactly 0.01 USDC.
4. Check the settlement transaction and payer against the sponsor purchase log.

The published claim invitation requests the repository URL, framework,
settlement transaction hash, requested credit handle and Base payout address by
email to `partnerships@blockchainiq.co`. Claiming, paying and sending email are
manual operator actions; this package performs none of them automatically.
The sponsor decides eligibility, remaining slot availability and whether an
integration passes. A mock test or repository publication alone earns no payout.

Official references:

- [Bounty terms](https://www.blockchainiq.co/blog/x402-build-bounties)
- [API and Node payment example](https://www.blockchainiq.co/agents)
- [Current free catalog](https://www.blockchainiq.co/api/x402/v1)

## Payment boundaries

The implementation registers only Base and the exact EVM scheme, validates the
fixed endpoint and the full payment option before constructing the signer, and
independently inspects the typed authorization before delegating to it. It rejects
unknown fee fields, Permit2/approval flows and signing extensions. Bazaar discovery
metadata is permitted without installing any extension handlers. Requests forbid
redirects, omit credentials, bound response sizes and use a 25-second overall
paid-flow timeout. Provider errors remain terminal for that tool instance.

## License

MIT. See [LICENSE](LICENSE).