API Reference

Smart contract functions for building autonomous agents on Katanga. All contracts are deployed on Flare Testnet (Chain ID 114).

Legend

writeState-changing transaction

readFree view call (no gas)

adminOwner-only restricted

SupplierSupplier agent calls

BuyerBuyer agent calls

AdminProtocol admin only

AnyoneAny address can call

KatangaMarket

0x2c87D6ce66764AD63446b75DE580B2f8Aa0dD64a

Supplier registration, listing CRUD, category indexing, and price negotiation. The core marketplace contract.

9 write functions

7 read functions

16 total

Write Functions

registerSupplier(metadataURI: string)

writeSupplier

Register as a supplier by staking FLR. The metadataURI should point to a JSON file describing the supplier (name, logo, region, etc.).

Parameters

Name	Type
metadataURI	string

createListing(categoryHash: bytes32, priceUSD: uint256, metadataURI: string, shippingRegions: bytes32[], estimatedDeliveryDays: uint16)

writeSupplier

Create a new product listing. Category hash is keccak256 of the category string. Price is in USD with 6 decimals (e.g. 29990000 = $29.99).

Parameters

Name	Type
categoryHash	bytes32
priceUSD	uint256
metadataURI	string
shippingRegions	bytes32[]
estimatedDeliveryDays	uint16

Returns

uint256 listingId

updateListing(listingId: uint256, priceUSD: uint256, metadataURI: string, shippingRegions: bytes32[], estimatedDeliveryDays: uint16)

writeSupplier

Update an existing listing. Only the listing owner (supplier) can call this.

Parameters

Name	Type
listingId	uint256
priceUSD	uint256
metadataURI	string
shippingRegions	bytes32[]
estimatedDeliveryDays	uint16

deactivateListing(listingId: uint256)

writeSupplier

Mark a listing as inactive. It will no longer appear in category queries. Can be reactivated later.

Parameters

Name	Type
listingId	uint256

deregisterSupplier()

writeSupplier

Exit the protocol and reclaim staked FLR. All active listings must be deactivated first.

createIntent(listingId: uint256, proposedPrice: uint256)

writeBuyer

Buyer proposes a price for a listing. Starts a negotiation flow. Price in USD with 6 decimals.

Parameters

Name	Type
listingId	uint256
proposedPrice	uint256

Returns

uint256 intentId

counterIntent(intentId: uint256, counterPrice: uint256)

writeSupplier

Supplier counters with a different price. The negotiation continues until one side accepts or rejects.

Parameters

Name	Type
intentId	uint256
counterPrice	uint256

acceptIntent(intentId: uint256)

writeSupplier

Accept the current negotiated price. Either party can call this to finalize the deal.

Parameters

Name	Type
intentId	uint256

rejectIntent(intentId: uint256)

writeSupplier

Reject the negotiation. Closes the intent permanently.

Parameters

Name	Type
intentId	uint256

Read Functions

getSupplier(supplier: address)

readAnyone

Returns supplier data: metadataURI, stake amount, active listing count, registration timestamp, active flag.

Parameters

Name	Type
supplier	address

Returns

Supplier struct

getListing(listingId: uint256)

readAnyone

Returns full listing data: supplier, category, price, metadata URI, regions, delivery estimate, active flag.

Parameters

Name	Type
listingId	uint256

Returns

Listing struct

getListingsByCategory(categoryHash: bytes32, offset: uint256, limit: uint256)

readAnyone

Paginated query of active listings in a category. Use offset/limit for pagination.

Parameters

Name	Type
categoryHash	bytes32
offset	uint256
limit	uint256

Returns

Listing[]

getListingsBySupplier(supplier: address)

readAnyone

Returns array of listing IDs owned by a supplier address.

Parameters

Name	Type
supplier	address

Returns

uint256[]

getListingCount()

readAnyone

Returns the total number of listings ever created (including inactive).

Returns

uint256

getMinimumStake()

readAnyone

Returns the minimum FLR stake required to register as a supplier. Currently 10 FLR on testnet.

Returns

uint256

getNegotiation(intentId: uint256)

readAnyone

Returns negotiation state: buyer, supplier, listing, proposed price, counter price, status, timestamps.

Parameters

Name	Type
intentId	uint256

Returns

Negotiation struct

KatangaEscrow

0x5a1BEB6425f700d0E3d02F9b6Ba954E1c7782250

Payment lock/release, full order lifecycle, dispute resolution, timeout claims, and partial refunds. Holds all buyer funds during fulfillment.

9 write functions

5 read functions

14 total

Write Functions

createEscrow(listingId: uint256, quantity: uint256, shippingHash: bytes32, paymentToken: address, amount: uint256)

writeBuyer

Lock payment tokens into escrow for a purchase. The buyer must have approved the escrow contract to spend the payment token first.

Parameters

Name	Type
listingId	uint256
quantity	uint256
shippingHash	bytes32
paymentToken	address
amount	uint256

Returns

uint256 escrowId

acceptOrder(escrowId: uint256)

writeSupplier

Supplier accepts the order and commits to fulfillment. Starts the delivery countdown.

Parameters

Name	Type
escrowId	uint256

markShipped(escrowId: uint256, trackingHash: bytes32)

writeSupplier

Record shipment with a tracking hash (keccak256 of tracking number). Starts the dispute window.

Parameters

Name	Type
escrowId	uint256
trackingHash	bytes32

confirmDelivery(escrowId: uint256)

writeBuyer

Buyer confirms receipt. Releases escrowed funds to supplier minus 2.5% protocol fee.

Parameters

Name	Type
escrowId	uint256

cancelOrder(escrowId: uint256)

writeBuyer

Cancel an order before it has been accepted by the supplier. Full refund to buyer.

Parameters

Name	Type
escrowId	uint256

openDispute(escrowId: uint256, reason: string)

writeBuyer

Open a dispute within the 7-day dispute window after shipment. Freezes funds until resolution.

Parameters

Name	Type
escrowId	uint256
reason	string

resolveDispute(escrowId: uint256, buyerWins: bool)

adminAdmin

Admin resolves a dispute. If buyerWins is true, funds return to buyer. Otherwise, released to supplier.

Parameters

Name	Type
escrowId	uint256
buyerWins	bool

claimTimeout(escrowId: uint256)

writeSupplier

Claim funds after the 14-day timeout period. If buyer never confirms delivery, supplier can claim.

Parameters

Name	Type
escrowId	uint256

partialRefund(escrowId: uint256, buyerPercentage: uint256)

adminAdmin

Split escrowed funds between buyer and supplier by percentage (0-100). Used for compromise resolutions.

Parameters

Name	Type
escrowId	uint256
buyerPercentage	uint256

Read Functions

getEscrow(escrowId: uint256)

readAnyone

Returns full escrow data: buyer, supplier, listing, token, amount, status, timestamps, tracking hash.

Parameters

Name	Type
escrowId	uint256

Returns

Escrow struct

getEscrowsByBuyer(buyer: address)

readAnyone

Returns array of escrow IDs where the given address is the buyer.

Parameters

Name	Type
buyer	address

Returns

uint256[]

getEscrowsBySupplier(supplier: address)

readAnyone

Returns array of escrow IDs where the given address is the supplier.

Parameters

Name	Type
supplier	address

Returns

uint256[]

getEscrowCount()

readAnyone

Returns total number of escrows ever created.

Returns

uint256

isAcceptedToken(token: address)

readAnyone

Check if a given ERC-20 token address is accepted for escrow payments (currently USDT0).

Parameters

Name	Type
token	address

Returns

bool

KatangaReputation

0x8ec32486dD83bc4AE8eBdEd57CC4B3DC4f1a6cC5

On-chain reputation scoring derived from escrow outcomes. Scores are computed from completed orders, disputes, and volume. Only the escrow contract can write to this.

0 write functions

2 read functions

2 total

Read Functions

getScore(supplier: address)

readAnyone

Returns the full reputation breakdown for a supplier: order counts, dispute count, total USD volume, computed score (0-100), and last update timestamp.

Parameters

Name	Type
supplier	address

Returns

SupplierScore struct (completedOrders, totalOrders, disputes, totalVolume, score, lastUpdated)

getReputationScore(supplier: address)

readAnyone

Returns just the numeric reputation score (0-100). Convenience method for agents that only need the score.

Parameters

Name	Type
supplier	address

Returns

uint256

Network Details

Network: Flare Testnet

Chain ID: 114

RPC: https://coston2-api.flare.network/ext/C/rpc

Payment Token: USDT0 (ERC-20)